NAME
drawmap - draw customized maps, using raw USGS data files
SYNOPSIS
drawmap [-l latitude1,longitude1,latitude2,longitude2] [-L]
[-o output_file.sun] [-d dem_file1 [-d dem_file2 [...]]]
[-c contour_interval_in_meters]
[-C contour_interval_in_meters]
[-g gnis_file] [-a attribute_file] [-x x_size] [-y y_size]
[-w] [-n color_table_number] [-r relief_factor] [-z]
[-i] [-h] [-t] [dlg_file1 [dlg_file2 [...]]]
VERSION
This is the manual page for version 2.5 of drawmap.
DESCRIPTION
The U.S. Geological Survey, and other sources, support 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. 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 arc-seconds apart; and you will often hear these files
called 3-arc-second files. In terms of distance along the
ground, the sample spacing varies with latitude. It is
generally less than 100 meters. (The "250K" means that the data
were digitized from a map at the scale of 1:250,000.) Files of
this type are currently available for free download from the
USGS.
24K Digital Elevation Model (DEM) files (in the classic format or the
SDTS format)
These files usually result from digitizing a "quad" map sheet.
(Each 1-degree block of latitude and longitude, covered by a
250K DEM file, is further subdivided into an 8-by-8 grid to
produce smaller blocks called quads.) The number of samples in
each direction varies, from quad to quad, but there is roughly
one sample per second of arc. These files differ from the 250K
DEM files in that the samples are spaced a fixed number of
meters apart rather than a fixed number of arc-seconds. Because
each quad represents an area that is 7.5 minutes of latitude by
7.5 minutes of longitude, you will also hear these files called
7.5-minute DEMs. The USGS provides 24K DEM data for free
download, in the Spatial Data Transfer System (SDTS) format.
Some files in the older format are available from other sources,
and may be available for purchase from the USGS.
100K Digital Line Graph (DLG) files (in the optional format or the
SDTS format)
These files come in collections, each of which covers a quarter
of the one-degree square covered by a 250K 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. Files of this
type are currently available for free download from the USGS, in
either the ’optional’ format or the SDTS format.
24K Digital Line Graph (DLG) files (in the optional format or the
SDTS format)
Like the 24K DEM files, each of these files covers a single
quad. Except for their inherently greater detail, these files
are essentially the same as the 100K DLG files. As with the 24K
DEM files, these files are freely available in SDTS format, but
are harder to come by in the ’optional’ format.
GTOPO30 files
GTOPO30 files are similar to 250K DEM files, but with samples
spaced 30 arc-seconds apart, and with a quite different format.
(For the purposes of this manual page, you can consider GTOPO30
files as just another variety of DEM files.) While these files
have relatively low resolution, they have the virtue of
providing full coverage for the entire planet. Furthermore,
they are currently available for free download.
Geographic Names Information System (GNIS) files
These files are basically lists of place names, with the
addition of latitude/longitude and other information. They are
available for free download.
If a DEM or DLG file is one of the above types, and is from the USGS,
there is a good chance that drawmap can use it. However, given the
range of available files, this is not a certainty. For example, the
USGS used to distribute 100K DLG files in ’standard’ format, with the
characters ’std’ as part of the file name. Neither the USGS nor
drawmap support these files anymore, but you may still be able to
obtain them. There is also a certain amount of variability in the
format of USGS SDTS files, and drawmap may not be able to handle some
of the variants, especially if I have never obtained a relevant sample
file to test against. Files from non-USGS sources may also be usable.
However, people don’t always strictly follow the relevant standards
when they create DEM or DLG files, and the standards can sometimes be
difficult to interpret, and drawmap isn’t infinitely adaptable, so not
all files can be processed.
Using the data in the various 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 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. However, I prefer
them only in the sense that I have them on my system. I would imagine
that other packages would be quite satisfactory as well.)
Map Projection Used by Drawmap
The only type of map projection currently supported is not technically
a projection at all, but simply a grid of latitudes and longitudes.
(The word "projection" is a mathematical term describing the
"stretching" of the earth’s roughly-spherical surface onto a flat map.)
Over limited areas, this latitude/longitude grid approximates a family
of projections called cylindrical projections. 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 several reasons for using this approach. First, the 250K DEM
data contain sample points that are evenly spaced in degrees of
latitude and longitude, making a simple grid the natural choice.
(Drawmap was originally written solely with 250K DEM data in mind.)
Second, this is an intuitive projection for small-area maps. Over
small areas, it approximates the Transverse Mercator projection, a
cylindrical projection that is often used for topographic maps. Third,
the USGS DLG data and 24K DEM data are specified in Universal
Transverse Mercator (UTM) coordinates, which are based on a rectangular
grid of x-y distances. Over small areas, degrees of arc make a
reasonable substitute for x-y distances, as long as the horizontal and
vertical directions are appropriately scaled. And, finally, the
latitude/longitude grid is also acceptable for large-scale maps. Since
users of drawmap can produce maps covering any amount of territory, the
latitude/longitude grid is a lowest-common-denominator that can handle
any request.
Introduction to UTM
In order to find your way around the 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.
Included with drawmap are two programs, utm2ll and ll2utm, that you can
use to convert back and forth between UTM coordinates and
latitude/longitude coordinates. You don’t really need these to use
drawmap, but they are useful in their own right. (Be sure to read the
associated manual pages to get information on conversion accuracy.)
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 flat rectangles; and these
deviations get larger as the distances from the central meridian and
equator increase.
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
poles (reaching infinity at the poles themselves). This gives the map
some useful directional properties, but grossly distorts shapes and
areas near the poles. (You can approximate this kind of stretching
with drawmap by using the "-x" and "-y" options to vary the number of
pixels per longitudinal or latitudinal degree; but remember that,
within a drawmap map, latitude and longitude always vary linearly.)
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, 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"
in the mathematical sense, meaning that it preserves angles (and hence
shapes and areas) within small areas of the resulting map. The
classical Mercator projection is also conformal in the cartographic
sense, meaning that it preserves angles everywhere on the map. (In
other words, if the great-circle route from Newark to Peoria is X
degrees east-of-north on the globe, then a straight line from Newark to
Peoria on a classical Mercator map is also at an angle of X degrees
east-of-north.) Of course, over large areas, the classical Mercator
projection can grossly distort shapes and areas.
Since, with drawmap, you can define your own image boundaries, the
output map may span any portion of one or more UTM zones, and zero or
more central meridians may appear at arbitrary positions within the map
boundaries. Over small areas, stretching latitude/longitude angles
into a square grid (which is what drawmap does) produces roughly the
same map image as a square grid of UTM coordinates would. Try to keep
the map area smaller than a UTM zone, and center the map on a central
meridian, if you want to use the map as a UTM surrogate. UTM
coordinates are usually used for areas much smaller than a UTM zone,
such as a 7.5-minute USGS quad. For such small areas, the geometrical
difference between latitude/longitude angles and surface distances is
small.
Introduction to the Different File Types
At the time this manual page was updated (August, 2001), various DEM,
DLG, and GNIS files were available for free download by following
appropriate links from http://mapping.usgs.gov/. For some files,
convenient graphical interfaces were available to let you locate
desired files by clicking on a map. Some DEM, DLG, and GNIS files, and
the GTOPO30 files too, were available via FTP from edcftp.cr.usgs.gov,
in the pub/data directory. (In the case of GNIS files, there was
simply a pointer to another download site.) Access to the various
files changes over time, so you may have to do some searching to find
what you want.
Ordinary DEM and DLG files (that is, non-SDTS and non-GTOPO30 DEM and
DLG files) are in (gzip-compressed) ASCII text format, and are human
readable (when uncompressed) except that they generally don’t contain
linefeeds to structure them into easily-editable lines of text. (Some
newer DLG files do have linefeeds; and I have come across some DEM
files with linefeeds also.) The web site provides information on how
to add linefeeds 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 the files in
uncompressed form. It is okay to have linefeeds in ordinary DLG files,
as long as no line is longer than 80 bytes (including the linefeed);
and it is okay to have linefeeds in ordinary DEM files, as long as no
line is longer than 1024 bytes (including the linefeed). The drawmap
distribution contains the block_dlg and block_dem programs to add
appropriate linefeeds to DLG and DEM files but, beyond that, you are on
your own if you want to muck around inside the files.
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 linefeeds to a DLG file (using the block_dlg program),
deleted a record, added a record, and then used 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.
Using SDTS files is a bit more complicated. SDTS data generally come
in the form of tar archives, compressed with gzip. Each such archive
should be unpacked into a separate directory. This is true even if
there are several archives in a single directory on the download site.
(Transportation archives, for example, normally come in triples --- one
each for roads, railroads, and other transportation features. These
triple archives should be unpacked into three different directories to
avoid files from one archive overwriting files from another.)
When you provide SDTS files as input to drawmap, you don’t have to
include all of the unpacked files on the command line. For DEM files,
each archive should contain one or more files with names like
????CEL@.DDF, where the ’?’ symbol stands for any single character, and
the ’@’ symbol stands for any single digit. Use one or more of these
file names (each preceded by "-d") just as you would an old-style DEM
file name, and drawmap will figure out the names of the other files in
the archive.
For DLG files, each archive should contain one or more files with names
like ????LE@@.DDF. Use one or more of these file names just as you
would an optional-format DLG file name. There is also a Master Data
Dictionary available for each kind of DLG file. At present, drawmap
makes no use of these.
Once you have unpacked the archives, you can compress the individual
files with gzip if you wish. If you do compress them, compress every
file that has a ".DDF" extension. You can also change the file names
to all lower case, but don’t mix and match upper and lower case files.
Other than changing upper to lower case, DO NOT change the file names.
Drawmap uses the file names to deduce what to do.
The GTOPO30 files also come in archives, and must be unpacked before
use. (You don’t need to unpack each archive into a separate directory,
but it isn’t a bad idea.) Once they are unpacked, you can compress the
individual files if you wish, as long as you compress both the ".HDR"
file and the ".DEM" file, which are the only files that drawmap uses.
(The same guidelines apply as for SDTS files: try to be consistent
with upper/lower case, compression, and the like.)
There is one GTOPO30 archive that contains a Polar Stereographic
projection of Antarctica. Drawmap can’t handle that one. On the FTP
site, there is also a gtopo30hydro directory. The files in this
directory are derived from GTOPO30 data, but use a Lambert Azimuthal
Equal Area projection. Drawmap does not currently handle these either.
To use GTOPO30 files, simply invoke the "-d" option, and provide as a
parameter the file whose name ends in ".HDR" (or ".HDR.gz" if you
compressed the individual files). Use caution with GTOPO30 data. Each
data set spans a large area, and the memory needed to read it all in
can be enormous. You can limit the amount of memory required by using
the "-l" option to restrict the range of the image to a subset of the
available GTOPO30 data.
Be careful with downloads. Some download software will uncompress gzip
files during a download but still store the files with a ".gz" suffix.
Other download 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.
Drawmap Tidbits
If you provide all three types of data (DEM, DLG, and GNIS) as input,
then drawmap will first produce a shaded relief map (or, when "-c" or
"-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.
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" or "-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" or "-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, longitude, and elevation 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,
and about the exact maximum and minimum elevations.) If only one DEM
file is supplied, the location name from the DEM file header will be
included in the title. (Sometimes, it is hard to figure out exactly
what the correct name is, so don’t be surprised if the title looks a
bit strange.)
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 (if there is room) will
have text next to them that specifies the latitude/longitude. Tick
marks can be turned off with the "-t" option.
North is always at the top of the map, and east is always at the right.
OPTIONS
-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.
-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. (If you use the
"-h" option, and provide no name, then "drawmap.pgm" is used.)
-d dem_file
You can provide as many DEM files as you want. (There is a
hard-coded limit of 1000 files in the source code, but it is
easily changed.) Since each file covers a limited area, 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" or "-C"
option, there will be anomalous contour lines along the edges of
these white areas. If you are using 24K DEM data, there may
also be anomalous contour lines around the outer boundaries of
the map.
The DEM files will be processed into multicolored shaded relief
(or contour lines), 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" or "-C" option, along
with data from DEM files), then you probably don’t want to
provide any DEM files. The DEM data would mix with the DLG
contour lines to produce a confusing morass.
Note that files are processed in the order given. Thus, if you
want to provide a 250K DEM file, and overlay parts of it with
one or more 24K DEM files, then you want to have the 250K DEM
file first in the argument list. This overlays the high-
resolution data over top of the low-resolution data.
Furthermore, the decision of whether or not to smooth the final
image is made based on the last DEM file processed. It is
usually desirable to base this decision on the highest-
resolution data present.
-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 (orange lines on a
white background) 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 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. On the other hand, the DLG data is likely to be more
precise about the locations of contours.
-C contour_interval_in_meters
This option is exactly the same as the "-c" option, except that
it doesn’t use a white background. Instead, it fills in the
areas between the orange contour lines using a rotating set of
solid colors. These distinct colors make it easier to follow
elevation contours as they swirl around the map. (The colors
come from the same set used to generate shaded relief, except
that white is excluded because it tends to stand out too much
from the other colors.)
-g gnis_file
Only one GNIS file is allowed. This is not really a restriction
since you can edit these files with an ordinary text editor,
making them 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.
WARNING: The format of both kinds of GNIS files has changed;
and drawmap will not properly process the older files. If place
names don’t show up on your maps, then you may need to download
newer GNIS files. The newer files have records that begin with
a postal code, like NJ, NY, or WY.
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. These fields can help
you to narrow down your choices.
The place names are added to the image on top of any other
features that you choose to include. A small "+" sign denotes
the actual location of the feature.
-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
50 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, ensures 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.)
At present, drawmap makes no use of Node data from the DLG
file(s). Thus, there is no need for any "N" entries in the
attribute file.
If no attribute file is given, drawmap will ignore the Area data
from the DLG file. If Area attributes are specified in an
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 possible for the outside of an area
to be filled in instead of the inside. (I have had this happen
often in practice, especially when stretching a map in one
direction by specifying unusual map dimensions with the "-x" and
"-y" options.) This potential problem is the reason why areas
are not filled in unless you make an explicit request in an
attribute file.
Another 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 comments in the
drawmap source code. One solution to both of these problems is
to not have drawmap fill any areas. Instead, fill in the areas
yourself using an image editor.
The distribution for drawmap includes a file, called
"attrib_codes," which is pulled from a USGS guide, and describes
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.
(Both of these files are probably somewhat dated. More current
information can be obtained by downloading the appropriate
standards documents from the USGS.)
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.)
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.
Roads and trails show up in red, pipelines and railroads in
black, hydrographic features in blue, hypsographic data in
orange, boundaries in gray, vegetative features in green, and
other data in black.
-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 250K DEM data can be
displayed at one half of full resolution.
As a special case, if you give only a single DEM file, and don’t
use the "-l", "-x", or "-y" options, drawmap will automatically
produce a complete map at full resolution.
For most 250K DEM files, full resolution is 1200 pixels per
degree of longitude or latitude, but it is 400 or 600 pixels per
degree of longitude for Alaskan files. The full resolution of
GTOPO30 files is 120 pixels per degree. For 24K DEM files,
resolution is more complicated. The data in these files are
sampled on a uniform UTM grid instead of on a latitude/longitude
grid, and the elevations may be sampled at spacings of 10 or 30
meters, and the number of samples varies with latitude. Thus,
the resolution (in terms of latitude and longitude) can vary
considerably from file to file. I use 3600 pixels per degree as
a very rough rule of thumb. It is a reasonable approximation
for files (with 30-meter spacing) in equatorial regions, but
becomes considerably less accurate as one moves north or south.
I like this particular number because it is exactly equal to the
number of arc-seconds in a degree.
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
otherwise imply.
Note also, that it is best to choose x and y values that are
some integer multiple or sub-multiple of the resolution of the
DEM data. For 250K DEM data, the resolution "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.
Similar comments apply to DEM files for Alaska, except that full
resolution is 400 or 600 pixels per degree of longitude.
GTOPO30 files are also similar to 250K DEM files, but their full
resolution is ten times smaller.
The situation for 24K DEM files is more complicated, since they
aren’t perfectly rectangular. You may have to try a few
different "-x" and "-y" values until you get good results. One
starting point is to provide a single 24K DEM file, without
using the "-l", "-x", or "-y" options. Drawmap will display the
image in full resolution, and will tell you what x and y values
it picks. (Alternatively, you can use the "-i" option to print
out some information about the DEM file, including its extent in
both the x and y directions.) You can use this information to
derive approximate x and y values for maps that contain multiple
24K DEM files. However, because of the odd shapes of the 24K
quads, you may still have to "twiddle" your derived values for
the best results.
Be careful about choosing x and y values that are near, but not
equal to, the full resolution of the data. Under these
conditions, drawmap has a hard time transferring the data to the
image without creating some image blemishes. As an example, if
the DEM data has a resolution of 1200 elevations per degree,
then an x or y value of 1190 or 1210 would not be the best
choice. These values for x or y would be likely to result in a
checkerboard effect in areas where the elevation changes slowly.
Note that, when the resolution of the source data doesn’t match
the resolution of the desired image, drawmap may silently apply
a filter to the source data, or to the output image, to blur
things out somewhat. This can improve the appearance of the
completed map. When the resolutions are about the same, no
filtering is done, because I prefer isolated image blemishes to
non-localized blurring of the map.
-w The DLG files describe bodies of water within land areas.
However, they don’t generally provide polygonal areas to define
sea-level water in coastal areas. When you use the "-w" option,
drawmap will attempt to make ocean areas bright blue, just like
the inland waterways. This feature is provided as an option,
rather than as the default, because it sometimes produces odd
results. For example, some DEM data in the Sacramento, CA, area
give elevations below sea level. With the "-w" option, the map
ends up with anomalous-looking sub-sea areas surrounded by
water. (This representation may, in fact, be correct. The
areas may be polders, pumped out for farming purposes. I don’t
know. But they look odd.)
-n color_table_number
Drawmap provides a choice of four color schemes for shaded
relief. The default is color table 2, which provides a natural-
looking color scheme. Using the "-n" option, you can instead
choose color table 1, a very-neutral non-obtrusive scheme; color
table 3, a natural-looking but garish scheme reminiscent of maps
in school textbooks; or color table 4, a very garish scheme
designed to provide good perception of variations in elevation.
From 1 to 4, the tables are ranked in order of increasing
obtrusiveness.
Note that the natural scheme isn’t perfect. What looks natural
for seacoast plains and mountains may not look as good for
highland plains and mountains. The selected color scheme is a
compromise. If you are adventurous, you can modify the software
to provide additional color tables of your own devising. The
software is specifically designed to make such modifications
reasonably painless, as long as you are familiar with the ’C’
programming language.
For elevations below sea level, drawmap simply re-uses one of
the colors used above sea level. A grayish or blueish color is
selected, if possible. The reason for the re-use is that sub-
sea-level areas are rare, and color table space is a scarce
commodity.
-r relief_factor
Normally, when drawing shaded relief, drawmap manipulates the
colors in the color table so as to provide maximum sharpness in
the relief. In other words, the shading varies from full
brightness all the way to black.
You can use the "-r" option to change this behavior. A
relief_factor of 1.0 duplicates the default behavior, and is the
same as providing no "-r" option at all. A relief_factor of 0.5
causes the colors to shade from full brightness down to half
brightness. A relief_factor of 0.0 yields full-brightness color
bands, with no shaded relief at all. (The "-r" option has no
effect when you are requesting contours with the "-c" or "-C"
option.)
You can provide any relief_factor you want, as long as it falls
in the range from 0.0 through 1.0. However, keep in mind that
the color tables are not infinitely adjustable. As you vary the
relief_factor from 0 through 1, the color scheme will change, at
most, eighteen times. Thus, it is pointless to provide lots of
digits of precision in the relief_factor.
One use of this feature is to provide faint shaded relief, as a
background for data you consider more important (such as roads
on a road map). For this application, you might choose color
table 1 or 2, with a relief_factor of 0.1.
-m relief_magnification
Some regions of the world are relatively flat, with only minor
relief. In such regions, it may be desirable to make the relief
stand out more sharply. The "-m" option allows you to supply a
magnification factor that enhances elevation differences. The
factor must be greater than or equal to 1.0, and the default
value is 1.0. (The "-m" option has no effect when you are
requesting contours with the "-c" or "-C" option.)
In order to use this feature, it is useful to know a little
about how shaded relief is generated. We begin by assuming that
the sun is shining from the northwest, so that slopes facing to
the north or west will be more brightly lit than slopes facing
south or east. At any given point on the map, we first note the
exact elevation of the point. This information is used to
select the overall color at that point, such as green, yellow,
red, brown, and so on. We then find the difference in elevation
between the given point and a couple of nearby points. These
results are used to make a rough estimate of the direction the
land is sloping at the given point. This estimate is then used
to modulate the light/dark shading of the point to reflect the
degree to which the point is in sun or in shade. The actual
degree of light/dark shading is the result of a hand-tuned
algorithm, developed largely through trial and error.
When you provide a magnification factor, the height differences
(between the given point and its neighbors) are multiplied by
the given factor. Thus, if a given height difference is Z
meters, and the magnification factor is 2, the shading is done
as if the height difference were 2Z meters. This may result in
a somewhat brighter highlight, or a somewhat deeper shadow, or
no noticeable change, depending on the direction that the land
is sloping. Note that the actual elevation of the point is not
modified. Thus, if the elevation calls for the point to be
green, it will remain green no matter how large a magnification
factor you provide. The only impact of the "-m" option is to
modify the light/dark shading at each point.
Don’t expect amazing results. The shading calculations are not
linearly related to height differences, so the magnification
factor has only a limited effect. To maximize perception of
height differences, you might want to try the "-z" option, with
or without the "-m" option. Remember too that drawmaps shading
is only a crude simulation of the light and shadow of real
relief. If you want more realistic shading, you might want to
use the "-h" option to generate a file of elevation data, which
can be imported into a ray-tracing program to produce a more
realistic three-dimensional appearance.
-z When the given DEM data span a small range of elevations, shaded
relief uses only a small portion of the color table. In fact,
if the range of elevations is small enough, the entire map may
end up using only a single color, with whatever light/dark
shading is called for by the limited roughness of the terrain.
This results in a pretty boring map.
For these situations, drawmap provides the "-z" option, which
specifies that the entire range of available colors be used to
represent the given terrain. For example, assume that the data
only contain elevations between 4567 feet and 5799 feet.
Normally (depending on the chosen color table), the color
"green" might represent elevations from 0 feet to 1000 feet, and
thus no green would appear in the map. With the "-z" option,
however, green will instead represent elevations from 4567 feet
to 4655 feet, and will show up in the low-lying areas of the
map. All of the other available colors will also show up, each
representing its proportion of the elevation range. (The "-z"
option has no effect when you are requesting contours with the
"-c" or "-C" option.)
-i When you provide this option, drawmap doesn’t produce a map.
Instead it prints out some useful information about all of the
DEM and DLG files that you specify on the command line.
For a DEM file, the information includes: the file name, the
DEM name, the latitude/longitude of the southeast and northwest
corners, the minimum and maximum elevation, the number of
samples in the x and y directions, and an indication of whether
or not the file contains linefeeds.
For a DLG file, the information includes: the file name, the
DLG name, the postal codes touched by the file (e.g. MT, TX,
RI), the type of data present in the file, the
latitude/longitude of the southeast and northwest corners, and
an indication of whether or not the file contains linefeeds.
Drawmap may not always be able to find the postal codes in a DLG
file, so don’t be upset if the field is blank. In DEM files,
the DEM name may contain some postal-code information, but not
always. SDTS files aren’t human-readable, so their linefeed
information is omitted.
When the "-i" option appears, all other options are ignored
except the "-d" option.
-h When you provide this option, drawmap doesn’t produce a map.
Instead it takes the DEM information and produces a height-field
file, in Portable Graymap (PGM) format. The file is readable
ASCII, beginning with the line "P2", which identifies the file
as a PGM file. The next line contains the x and y dimensions,
and the maximum elevation in the file, separated by white space.
Then the file includes all of the elevation samples, one per
line, beginning with the top west-to-east row, and followed by
all of the other rows in sequence. Finally, there are some
commentary lines containing information about the data,
including the latitude/longitude of the southeast and northwest
corners, and the minimum and maximum elevations.
This file is suitable for use by ray tracing programs (such as
the readily-available POV-Ray(tm) program) to produce
3-dimensional renderings of terrain. (It is also viewable by
some image viewers, such as the "xv" viewer, and can be used as
input to custom-built programs that process elevation data.)
Unless you select a file name, with the "-o" option, the file
will be called "drawmap.pgm".
Any elevations less than zero are bumped up to zero, and any
areas of the image that contain no DEM data have their
elevations set to zero. (In the latter case, the points are not
included when determining the minimum elevation in the file. In
the former case, the minimum elevation will be zero.)
Drawmap will also generate a file called "drawmap.pov". This
file is a rough attempt at a POV-Ray (version 3) file which,
together with the PGM file, can be used to produce a rendering
of the 3-dimensional terrain. The file will probably require
manual editing to get things the way you want them, but it is at
least a start. There are some minimal instructions, embedded in
the file as comments, but you are assumed to be familiar with
POV-Ray before you use the "-h" option.
-t Normally, drawmap will put tick marks and latitude/longitude
numbers around the borders of the map. However, for maps that
span large regions of the earth, these tick marks and numbers
can overlap and interfere with one another. Drawmap makes a
limited attempt (with emphasis on the word "limited") to reduce
the density of the markings as the map area increases. Rather
than try to adapt to any situation, though, I chose to provide
the "-t" option, which totally shuts off production of tick
marks and latitude/longitude legends. It is for use in
situations where the border markings become cumbersome.
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.
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
To 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 (full resolution would be 1200x1200):
drawmap -d santa_ana-w.gz -l 33,-117,34,-118 -x 300 -y 300
To 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
To add in some place names from a GNIS file (that 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
To 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/522274.HY.opt.gz
santa_ana-e_CA/hydrography/522275.HY.opt.gz
santa_ana-e_CA/hydrography/522276.HY.opt.gz
santa_ana-e_CA/hydrography/522279.HY.opt.gz
To draw a map of western Europe, using GTOPO30 data, first download the
w020n90.tar.gz and w020n40.tar.gz archives, and unpack them by typing:
gunzip -c w020n90.tar.gz | tar xf -
gunzip -c w020n40.tar.gz | tar xf -
Then draw a map by typing:
drawmap -t -x900 -y1200 -w -l30,20,70,-10 -d W020N90.HDR
-d W020N40.HDR
LIMITS
As distributed, drawmap is limited to 1000 DEM files, one GNIS file,
and one attribute file. The DEM limit is 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. The number of DLG files is only
limited by your system’s limits on command-line length.
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.
When dealing with 24K DEM data, there will often be visible seams
between the data from different files. There are several reasons for
this. First, there can be marked differences in data quality between
files. Lower quality data can have a lot of anomalous "fuzz", which
forms discontinuities with adjacent data of higher quality. Even if
one ignores other sources of discontinuity between data blocks, the
visual difference between the two quality levels can be quite obvious.
Second, the calculations used to map raw data into the image may
produce discontinuities, because numeric rounding may pull a data point
one way, at the edge of one block of data, and may push an adjacent
data point the other way, at the edge of the adjacent block of data.
Third, it goes without saying that there may be residual bugs in the
code that handles the DEM files.
Finally, there may be flaws in the data itself. For example, some 24K
SDTS DEM files, produced before January 2001, are known to have small
positional errors. (The non-SDTS DEM files don’t suffer from this
problem.)
Similar seams may appear between blocks of GTOPO30 data, but aren’t
usually as obtrusive.
There is another issue involving 24K DEM data. Each 24K quad
represents a latitude/longitude square, with one eighth of a degree on
each side. However, the native coordinate system for 24K DEM quads is
a UTM grid. In UTM coordinates, the latitude/longitude square becomes
an approximate quadrilateral, which often has no two sides of the same
length. The four sides of the quad will usually be tilted at slight
angles to the UTM axes. It is this odd-shaped quad that is stored in a
24K DEM file, as a set of elevation samples that are evenly-spaced in
UTM coordinates. (The spacing is normally 10 meters or 30 meters.)
Different columns of sample points may contain different numbers of
samples, depending on where the columns intersect the slanting sides of
the quad.
An evenly-spaced collection of UTM points does not map onto an evenly-
spaced set of latitude/longitude points. In order to map the UTM data
onto a latitude/longitude grid, drawmap must warp the points into new
relative positions, turning the unevenly-shaped UTM quadrilateral into
a latitude/longitude square. (You might picture this by imagining an
odd-shaped quad, which is cut out of a rubber sheet and covered with a
uniform grid of dots, and which is then stretched into a perfect
square.) During this warping process, rounding quantization can
produce some diagonal artifacts in the map image. (We could sidestep
this issue by making drawmap produce maps using an optional UTM grid,
rather than always using a latitude/longitude grid. However, drawmap
is not presently so endowed.)
Rounding quantization may also sometimes produce anomalous vertical and
horizontal linear features on the map, in the form of small
discontinuities in the changing elevation. This can happen for data of
any level of detail; and is a result of trying, for example, to stretch
a 100-by-100 grid of data points to cover a 101-by-101 grid of image
pixels. The data don’t quite fit, and something, somewhere, has to
give.
Whether artifacts are horizontal, vertical, or diagonal, their
incidence can sometimes be reduced by adjusting the values of the "x"
and "y" image dimensions. However, while this is usually
straightforward for 250K DEM or GTOPO30 data, it can be a challenge for
24K DEM data. This is because, while drawmap can tell you the height
and width, in UTM samples, for the raw 24K DEM data, it doesn’t know
how to figure out an optimal width and height after the data are warped
onto a latitude/longitude grid. Furthermore, when you provide more
than one 24K DEM file, there is no truly optimal width and height for
the image, because the quadrangle covered by each file has a slightly
different shape from the quadrangles adjoining it. What works well for
one quad may not be the best for another. I don’t have a general rule
of thumb for adjusting the width and height. I usually just try a few
minor tweaks, to the "x" and "y" values, and pick the one I like the
best.
Faced with various possible image artifacts, drawmap tries to smooth
things out, but faces a tradeoff between making the image look good
(and blurring some of the good data), or leaving the good data
unaltered (resulting in some esthetic imperfections). Drawmap tends to
err on the side of leaving good data untouched at the expense of
leaving some artifacts in isolated spots on the image. It tries
hardest to preserve the pristine data when the map image dimensions are
approximately the same as the resolution of the raw data. This is
because, in such cases, there is approximately a one-to-one mapping
between the raw data and pixels in the image. It seems useful to
preserve this correspondence, and not to blur it with smoothing
algorithms.
When you specify image dimensions that differ considerably from the
resolution of the data, drawmap takes more liberties in its attempt to
produce pleasing results. If the map resolution is greater than the
resolution of the data, then drawmap must replicate data points in
order to fill up the map. It does some smoothing on the finished image
to reduce the resulting "checkerboard" effect. If the data have
considerably greater resolution than the map image, then drawmap has
more data than it needs, so it averages adjacent data points to
determine each elevation in the map. Thus, one alternative for
reducing image artifacts is to produce a map at, say, half resolution.
If, for example, a 24K DEM file has a 300-by-400 sample grid, then you
might try drawing a map with "x" set to 150 and "y" set to 200. The
averaging operation will then smooth the data, which will usually
reduce image artifacts.
If you are using the "-c" or "-C" option, and the given DEM files do
not fully cover the image, there may be anomalous contour lines along
the borders of the valid data. (This happens when you fail to
completely tile the image with DEM files.) This problem is a result of
the way the contours are produced. It may get fixed some day, but
isn’t a high priority since it is usually hard to mistake these
anomalies for valid data.
The code that reads SDTS files is not a complete implementation of all
of the relevant standards involved in SDTS. In particular, SDTS relies
on the ISO 8211 standard, and it would not be at all difficult to
construct a valid ISO 8211 file that drawmap would be unable to read.
The code is intended to be smart enough to read SDTS files from the
USGS, and hopefully from other sources, but it is not necessarily smart
enough to read any file you might throw at it. If you find a USGS SDTS
file that drawmap can’t read, I would be interested in hearing about
it. (I can’t promise to fix the problem, because the range of
possibilities is large, and I don’t want to end up trying to support
every dialect that happens to pop up.)
Most of the SDTS DEM files I have examined store elevations as binary
two’s-complement integer numbers. Some files, however, store them as
binary floating-point numbers, in IEEE 754 format. When it encounters
such a file, drawmap simply assumes that your computer uses IEEE 754
floating point as its native floating point format. If this assumption
is not true, then the file won’t be correctly parsed.
There may be some DLG attribute codes that are not properly handled.
While I have downloaded and processed thousands of DLG files, in the
various supported formats, I can’t be sure that this subset of the
available files spans the full range of possibilities. Also, it is not
always clear, in the relevant specifications documents, exactly how
attributes should be encoded, in either the old-style DLG files or the
newer SDTS DLG files. I know of at least a few ambiguities that I am
not sure how to handle. These are documented in the source code.
Furthermore, there are numerous special cases, some of which appear to
involve relatively small subsets of the USA. I put a lot of effort
into trying to properly process the attributes, but it is difficult to
test every possible situation, and my patience for dealing with finicky
details is not infinite.
SEE ALSO
llsearch(1), utm2ll(1), ll2utm(1), block_dlg(1), block_dem(1),
sdts2dem(1), sdts2dlg(1), pgm(1)
Aug 1, 2001