\" =========================================================================
\" drawmap.1 - The manual page for the drawmap program.
\" Copyright (c) 1997  Fred M. Erickson
\"
\" This program is free software; you can redistribute it and/or modify
\" it under the terms of the GNU General Public License as published by
\" the Free Software Foundation; either version 2, or (at your option)
\" any later version.
\"
\" This program is distributed in the hope that it will be useful,
\" but WITHOUT ANY WARRANTY; without even the implied warranty of
\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
\" GNU General Public License for more details.
\"
\" You should have received a copy of the GNU General Public License
\" along with this program; if not, write to the Free Software
\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
\" =========================================================================
.TH DRAWMAP 1 \" -*- nroff -*-
.SH NAME
drawmap \- draw customized maps, using raw USGS data files
.SH SYNOPSIS
.B drawmap
[-l latitude1,longitude1,latitude2,longitude2] [-L]
[-o output_file.sun]
[\-a attribute_file] [\-x x_size] [\-y y_size]
[\-d dem_file1 [\-d dem_file2 [...]]] [\-g gnis_file]
[dlg_file1 [dlg_file2 [...]]]
.SH VERSION
This is the manual page for version 1.0 of drawmap.
.SH DESCRIPTION
The U.S. Geological Survey supports sites on the Internet with
many gigabytes of raw geographic data, mostly for the USA.
.I Drawmap
draws maps, using a subset of the available data for the USA.
The relevant subset includes:
.TP
.I "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.
.TP
.I "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.
.TP
.I "Geographic Names Information System (GNIS) files"
These files contain lists of place names, complete with their latitude/longitude and other information.
.PP
Using the data in these files,
.I 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).
.PP
The only type of map projection currently supported is a cylindrical (Transverse Mercator)
projection, with a square grid of latitudes and longitudes.
(By playing with the "-x" and "-y" options, you can make the grid non-square.)
There are two reasons for using this projection.
First, it is an intuitive projection for small-area maps,
often used for topological maps.
Second, the USGS DLG data are
specified in the Universal Transverse Mercator (UTM) system.
.PP
In order to find your way around the USGS 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.)
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.
.PP
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 way they preserve some valuable
feature(s) of a globe-shaped map (features like shape, area, distance, and direction).
In the Transverse Mercator projection used by
.I 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 within small areas of the resulting map.
.PP
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.
.PP
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 package is the "ImageMagick" package, but others are
available.  The "xv" package also has some useful features.)
.PP
At the time this manual page was written (October, 1997), the DEM and DLG files were available for free down load
from http://edcwww.cr.usgs.gov/, 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 file names
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
.I drawmap
is able to read and use the files in their native state (in
.I gzip
format, with a ".gz" suffix on the file name).
.I Drawmap
can also process them in uncompressed form, but will not be happy if you add newlines to them.
.PP
If you provide all three types of files (DEM, DLG, and GNIS) as input, then
.I drawmap
will first produce a shaded relief 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 is replaced by a simple white background.
.PP
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
.I 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.
.SS OPTIONS
.I 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 there is room, a color key will be placed at the
bottom of the map to help you interpret the shaded relief.
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.
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.
.TP
.B \-L
Print out the program license information and exit.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-d dem_file
You can provide as many DEM files as you want.  Since each one 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.)
The DEM files will be processed into multicolored shaded relief, which serves
as a background for any other features you add to the map.
If you are trying to draw a contour map, using hypsographic data, then you
probably don't want to provide any DEM files, since the shaded relief will
make the contour lines hard to follow.
.TP
.B \-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,
because otherwise the map would be plastered nearly solid with place names.
The GNIS data generally come in separate files for each US state.
The
.I llsearch
command allows you to extract all place names within a certain range
of latitudes and longitudes.
You can edit the resulting extracted data and make further reductions.
Each GNIS entry has a field that denotes its type, such as "ppl" for
populated places and "summit" for mountain tops.

The place names are added to the image on top of any other features that
you choose to include.
.TP
.B \-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 DLG area.)
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,
.I drawmap
parses Node data from the DLG file, but does nothing at all with it.

If no attribute file is given,
.I drawmap
will also ignore the Area data from the DLG file.
If Area attributes are specified in the attribute file, then
.I drawmap
will 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 file.

The distribution for
.I 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 an Area attribute specification that will
cause lakes and ponds 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.)
Thus, by specifying one or more 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.
.TP
.B \-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 most 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.
.I 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 "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.
If you want to specify your own values, with "-x" and "-y", then it is good to choose
an integer multiple or sub-multiple of 60.
(In this case, choices might include 30, 120, 240, and so on.)
If you choose strange values for x and y, then the program will 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.
.TP
.B 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.
.SS 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

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
.SS LIMITS
As distributed,
.I 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.