path: root/static/unix-v10/man7/map.7

.TH MAP 7
.CT 1 inst_info
.SH NAME
map \- draw maps on various projections
.SH SYNOPSIS
.B map
.I projection
[
.I param ...
]
[
.I option ...
]
.PP
.SH DESCRIPTION
.I Map
prepares on the standard output a
map suitable for display by any
plotting filter described in
.IR  plot (1).
A menu of projections is produced in response to an unknown
.IR projection .
For the meanings of
.I params
pertinent to particular projections
see
.IR  proj (3).
.PP
The default data for
.I map
are world shorelines.
Option
.B -f
accesses the higher-resolution World Data Bank II.
.TP
.BR -f " [ \fIfeature\fR ... ]"
Features are ranked 1 (default) to 4 from major to minor.
Higher-numbered ranks include all lower-numbered ones.
Features are
.RS
.TF country[1-3]
.TP
.BR shore [ 1 - 4 ] 
seacoasts, lakes, and islands; in the absence of
.BR -m ,
option
.B -f
automatically includes
.B shore1
.TP
.BR ilake [ 1 - 2 ] 
intermittent lakes
.TP
.BR river [ 1 - 4 ] 
rivers
.TP
.BR iriver [ 1 - 3 ] 
intermittent rivers
.TP
.BR canal [ 1 - 3 ] 
.BR 3 =irrigation
canals
.TP
.BR glacier
.TP
.BR iceshelf [ 12 ] 
.TP
.BR reef
.TP
.BR saltpan [ 12 ] 
.TP
.BR country [ 1 - 3 ] 
.BR 2 =disputed
boundaries,
.BR 3 =indefinite
boundaries
.TP
.BR state
states and provinces (US and Canada only)
.PD
.RE
.PP
In other options
coordinates are in degrees, with north latitude
and west longitude counted as positive.
.TP 0
.BI -l " S N E W"
Set the southern and northern latitude
and the eastern and western longitude limits.
Missing arguments are filled out from the list
\-90, 90, \-180, 180.
.TP
.BI -k " S N E W
Set the scale as if for a map with limits
.B -l
.I "S N E W"
and no
.B -w
option.
.TP
.BI -o " lat lon rot"
Orient the map in a nonstandard position.
Imagine a transparent gridded sphere around the globe.
Turn the overlay about the North Pole
so that the Prime Meridian (longitude 0)
of the overlay coincides with meridian
.I lon
on the globe.
Then tilt the North Pole of the
overlay along its Prime Meridian to latitude
.I lat
on the globe.
Finally again turn the
overlay about its `North Pole' so
that its Prime Meridian coincides with the previous position
of meridian
.IR rot .
Project the map in
the standard form appropriate to the overlay, but presenting
information from the underlying globe.
Missing arguments are filled out from the list
90, 0, 0.
In the absence of
.BR \-o ,
the orientation is 90, 0,
.I m,
where
.I m
is the middle of the longitude range.
.TP
.BI -w " S N E W"
Window the map by the specified latitudes
and longitudes in the tilted, rotated coordinate system.
Missing arguments are filled out from the list \-90, 90, \-180, 180.
(It is wise to give an encompassing
.B -l
option with
.BR -w .
Otherwise for small windows computing time
varies inversely with area!)
.TP
.BI -d " n"
For speed, plot only every
.IR n th
point.
.TP
.B  -r
Reverse left and right
(good for star charts and inside-out views).
.br
.ns
.TP
.B  -s1
.br
.ns
.TP
.B -s2
Superpose.  Outputs for a
.B -s1
map (no closing) and a
.B -s2
map (no opening) may be concatenated.
.TP
.BI -g " dlat dlon res"
Grid spacings are
.I dlat,
.I dlon.
Zero spacing means no grid.
Missing
.I dlat
is taken to be zero.
Missing
.I dlon
is taken the same as
.IR dlat .
Grid lines are drawn to a resolution of
.I res
(2\(de or less by default).
In the absence of
.BR \-g ,
grid spacing is 10\(de.
.TP
.BI -p " lat lon extent"
Position the point
.I lat, lon
at the center of a square plotting area.
Scale the map so that a side of the square is
.I extent
times the size of one degree of latitude
at the center.
By default maps are scaled and positioned
to fit within the plotting area.
An
.I extent
overrides option
.BR -k .
.TP
.BI -c " x y rot"
After all other positioning and scaling operations,
rotate the image
.I rot
degrees counterclockwise about the center 
and move the center to position
.I x, y,
of the plotting area, whose nominal extent is
.RI \-1 \(<= x \(<= 1,
.RI \-1 \(<= y \(<= 1.
The map is clipped to this area.
Missing arguments are taken to be 0.
.TP
.BR -m " [ \fIfile\fP ... ]"
Use
map data from named files.
If no files are named, omit map data.
Files that cannot be found directly are looked up
a standard directory, which contains, in addition to the
data for
.BR -f ,
.RS
.LP
.TF counties
.TP
.B world
World Data Bank I from CIA (default)
.TP
.B states
US map from Census Bureau
.TP
.B counties
US map from Census Bureau
.PD
.RE
.IP
The environment variables
.B MAP 
and
.B MAPDIR 
change the default
map and default directory.
.TP
.BI -b " \fR[ \fPlat1 lon1 lat2 lon2 \fR... ]"
Suppress the drawing of the normal boundary
(defined by options
.BR -l 
and
.BR -w ).
Coordinates, if present, define the vertices of a
polygon to which the map is clipped.
If only two vertices are given, they are taken to be the
diagonal of a rectangle.
To draw the polygon, give its vertices as a
.B -u
track.
.TP
.BI -t " file ..."
The arguments name ASCII files that
contain lists of points,
given as latitude-longitude pairs in degrees.
If the first file is named 
.LR - ,
the standard input is taken instead.
The points of each list are plotted as connected `tracks'.
.IP
Points in a track file may be followed by label strings.
A label breaks the track.
A label may be prefixed by
\f5"\fR,
.LR : ,
or 
.L !
and is terminated by a newline.
An unprefixed string or a string prefixed with
.L
"
is displayed at the designated point.
The first word of a
.L :
or
.L !
string names a special symbol (see option
.BR -y ).
An optional numerical second word is a scale factor
for the size of the symbol, 1 by default.
A
.L :
symbol is aligned with its top to the north; a
.L !
symbol is aligned vertically on the page.
.TP
.BI -u " file ..."
Same as
.BR -t ,
except the tracks are
unbroken lines.
.RB ( -t
tracks are dot-dash lines.)
.TP
.BI -y " file
The
.I file
contains 
.IR plot (5)-style
data for
.L :
or
.L !
labels in
.B -t
or
.B -u
files.
Each symbol is defined by a comment
.BI : name
then a sequence of
.L m
and
.L v
commands.
Coordinates (0,0) fall on the plotting point.
Default scaling is as if the nominal plotting range were
.LR "ra -1 -1 1 1" ;
.L ra
commands in
.I file
change the scaling.
.SH EXAMPLES
.TP
.L
map perspective 1.025 -o 40.75 74
A view looking down on New York from 100 miles
(0.025 of the 4000-mile earth radius).
The job can be done faster by limiting the map so as not to `plot'
the invisible part of the world:
.LR "map perspective 1.025 -o 40.75 74 -l 20 60 30 100".
A circular border can be forced by adding option
.LR "-w 77.33" .
(Latitude 77.33\(de falls just inside a polar cap of
opening angle arccos(1/1.025) = 12.6804\(de.)
.TP
.L
map mercator -o 49.25 -106 180
A map whose `equator' is a great circle pasing east-west
through New York.
The pole of the map is placed 90\(de away (40.75+49.25=90)
on the
other side of the earth.
A 180\(de twist around the pole of the map arranges that the
Prime Meridian of the map runs from the pole of the
map over the North Pole to New York
instead of down the back side of the earth.
The same effect can be had from
.L
map mercator -o 130.75 74
.TP
.L
map albers 28 45 -l 20 50 60 130 -m states
A customary curved-latitude map of the United States.
.TP
.L
map albers 28 45 -l 20 50 60 130 -y yfile -t tfile
An example of tracks, labels, and symbols.
Arrows at New York and Miami are 8% and 12%
as long as the map is wide.
The contents of 
.L yfile
and
.L tfile
are
.nf
.ft L
.ta 3i
ra -50 -50 50 50	25.77 80.20 :arrow 12	
:arrow	25.77  80.20 Miami
m -1 0	25.77  80.20 
v 0 0	35.00  74.02
v -.6 .3	40.67  74.02 !arrow 8
m -.6 -.3	40.67  74.02 " New York	
v 0 0	34.05 118.25 Los Angeles
.ft
.TP
.L
map harrison 2 30 -l -90 90 120 240 -o 90 0 0
A fan view covering 60\(de on either
side of the Date Line, as seen from one earth radius
above the North Pole gazing at the
earth's limb, which is 30\(de off vertical.
Option
.B -o
overrides the default
.BR "-o 90 0 180" , 
which would rotate
the scene to behind the observer.
.SH FILES
All files in directory $MAPDIR
.TF counties
.TP
.F [1-4]??
World Data Bank II for option
.B -f
.TP
.BR world , states , counties
default and other maps for option
.B -m
.TP
.F *.x
map indexes
.TP
.F map
the program proper
.SH "SEE ALSO"
.IR map (5), 
.IR proj (3), 
.IR plot (1)
.SH DIAGNOSTICS
`Map seems to be empty'\(ema coarse survey found
zero extent within the 
.B -l
and
.BR -w 
bounds; for maps of limited extent
the grid resolution,
.I res,
or the limits may have to be refined.
.SH BUGS
The syntax of range specifications in
.B -y
files differs from that in options.
.br
Windows (option
.BR -w )
cannot cross the Date Line.
.br
No borders appear along edges arising from
visibility limits.
.br
Segments that cross a border are dropped, not clipped.
.br
Certain very long line segments are dropped on the assumption
that they were intended to go the other way around the world.
.br
Automatic scaling may miss the extreme points of
peculiarly shaped maps; use option
.B -p
to recover.
.br
Although
.I map
draws grid lines dotted and
.B -t
tracks dot-dashed, many plotting filters
cannot cope and make them solid.