MAP(7)                                                     MAP(7)

     NAME
          map, mapdemo - draw maps on various projections

     SYNOPSIS
          map projection [ option ... ]

          mapdemo

     DESCRIPTION
          Map prepares on the standard output a map suitable for dis-
          play by any plotting filter described in plot(1). A menu of
          projections is produced in response to an unknown
          projection. Mapdemo is a short course in mapping.

          The default data for map are world shorelines.  Option -f
          accesses more detailed data classified by feature.

          -f [ feature ... ]
               Features are ranked 1 (default) to 4 from major to
               minor.  Higher-numbered ranks include all lower-
               numbered ones.  Features are

               shore[1-4]    seacoasts, lakes, and islands; option -f
                             always shows shore1
               ilake[1-2]    intermittent lakes
               river[1-4]    rivers
               iriver[1-3]   intermittent rivers
               canal[1-3]    3=irrigation canals
               glacier
               iceshelf[12]
               reef
               saltpan[12]
               country[1-3]  2=disputed boundaries, 3=indefinite
                             boundaries
               state         states and provinces (US and Canada only)

          In other options coordinates are in degrees, with north lat-
          itude and west longitude counted as positive.

          -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, or lesser
               limits suitable to the projection at hand.

          -k S N E W
               Set the scale as if for a map with limits -l S N E W .
               Do not consider any -l or -w option in setting scale.

          -o lat lon rot

     Page 1                       Plan 9             (printed 3/28/24)

     MAP(7)                                                     MAP(7)

               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
               lon on the globe.  Then tilt the North Pole of the
               overlay along its Prime Meridian to latitude 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 rot. Project the map in
               the standard form appropriate to the overlay, but pre-
               senting information from the underlying globe.  Missing
               arguments are filled out from the list 90, 0, 0.  In
               the absence of -o, the orientation is 90, 0, m, where m
               is the middle of the longitude range.

          -w S N E W
               Window the map by the specified latitudes and longi-
               tudes in the tilted, rotated coordinate system.  Miss-
               ing arguments are filled out from the list -90, 90,
               -180, 180.  (It is wise to give an encompassing -l
               option with -w.  Otherwise for small windows computing
               time varies inversely with area!)

          -d n For speed, plot only every nth point.

          -r   Reverse left and right (good for star charts and
               inside-out views).

          -v   Verso.  Switch to a normally suppressed sheet of the
               map, such as the back side of the earth in orthographic
               projection.

          -s1
          -s2  Superpose; outputs for a -s1 map (no closing) and a -s2
               map (no opening) may be concatenated.

          -g dlat dlon res
               Grid spacings are dlat, dlon. Zero spacing means no
               grid.  Missing dlat is taken to be zero.  Missing dlon
               is taken the same as dlat. Grid lines are drawn to a
               resolution of res (2° or less by default).  In the
               absence of -g, grid spacing is 10°.

          -p lat lon extent
               Position the point lat, lon at the center of the plot-
               ting area.  Scale the map so that the height (and
               width) of the nominal plotting area is 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 extent overrides option -k.

          -c x y rot

     Page 2                       Plan 9             (printed 3/28/24)

     MAP(7)                                                     MAP(7)

               After all other positioning and scaling operations have
               been performed, rotate the image rot degrees counter-
               clockwise about the center and move the center to posi-
               tion x, y, where the nominal plotting area is -1≤x≤1,
               -1≤y≤1.  Missing arguments are taken to be 0.  -x Allow
               the map to extend outside the nominal plotting area.

          -m [ file ... ]
               Use map data from named files.  If no files are named,
               omit map data.  Names that do not exist as pathnames
               are looked up in a standard directory, which contains,
               in addition to the data for -f,

               world     World Data Bank I (default)
               states    US map from Census Bureau
               counties  US map from Census Bureau

               The environment variables MAP and MAPDIR change the
               default map and default directory.

          -b [lat0 lon0 lat1 lon1... ]
               Suppress the drawing of the normal boundary (defined by
               options -l and -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 -u track.

          -t file ...
               The files contain lists of points, given as latitude-
               longitude pairs in degrees.  If the first file is named
               `-', the standard input is taken instead.  The points
               of each list are plotted as connected `tracks'.

               Points in a track file may be followed by label
               strings.  A label breaks the track.  A label may be
               prefixed by ", `:', or `!'  and is terminated by a new-
               line.  An unprefixed string or a string prefixed with "
               is displayed at the designated point.  The first word
               of a `:' or `!'  string names a special symbol (see
               option -y).  An optional numerical second word is a
               scale factor for the size of the symbol, 1 by default.
               A `:' symbol is aligned with its top to the north; a
               `!'  symbol is aligned vertically on the page.

          -u file ...
               Same as -t, except the tracks are unbroken lines.  (-t
               tracks appear as dot-dashed lines if the plotting fil-
               ter supports them.)

          -y file
               The file contains plot(6)-style data for `:' or `!'

     Page 3                       Plan 9             (printed 3/28/24)

     MAP(7)                                                     MAP(7)

               labels in -t or -u files.  Each symbol is defined by a
               comment :name then a sequence of `m' and `v' commands.
               Coordinates (0,0) fall on the plotting point.  Default
               scaling is as if the nominal plotting range were `ra -1
               -1 1 1'; `ra' commands in file change the scaling.

        Projections
          Equatorial projections centered on the Prime Meridian (lon-
          gitude 0).  Parallels are straight horizontal lines.

          mercator       equally spaced straight meridians, conformal,
                         straight compass courses
          sinusoidal     equally spaced parallels, equal-area, same as
                         `bonne 0'.
          cylequalarea lat0
                         equally spaced straight meridians, equal-
                         area, true scale on lat0
          cylindrical    central projection on tangent cylinder
          rectangular lat0
                         equally spaced parallels, equally spaced
                         straight meridians, true scale on lat0
          gall lat0      parallels spaced stereographically on prime
                         meridian, equally spaced straight meridians,
                         true scale on lat0
          mollweide      (homalographic) equal-area, hemisphere is a
                         circle
                         gilbert() sphere conformally mapped on hemi-
                         sphere and viewed orthographically
          gilbert        globe mapped conformally on hemisphere,
                         viewed orthographically

          Azimuthal projections centered on the North Pole.  Parallels
          are concentric circles.  Meridians are equally spaced radial
          lines.

          azequidistant  equally spaced parallels, true distances from
                         pole
          azequalarea    equal-area
          gnomonic       central projection on tangent plane, straight
                         great circles
          perspective dist
                         viewed along earth's axis dist earth radii
                         from center of earth
          orthographic   viewed from infinity
          stereographic  conformal, projected from opposite pole
          laue           radius = tan(2xcolatitude), used in X-ray
                         crystallography
          fisheye n      stereographic seen from just inside medium
                         with refractive index n
          newyorker r    radius = log(colatitude/r): New Yorker map
                         from viewing pedestal of radius r degrees

     Page 4                       Plan 9             (printed 3/28/24)

     MAP(7)                                                     MAP(7)

          Polar conic projections symmetric about the Prime Meridian.
          Parallels are segments of concentric circles.  Except in the
          Bonne projection, meridians are equally spaced radial lines
          orthogonal to the parallels.

          conic lat0     central projection on cone tangent at lat0
          simpleconic lat0 lat1
                         equally spaced parallels, true scale on lat0
                         and lat1
          lambert lat0 lat1
                         conformal, true scale on lat0 and lat1
          albers lat0 lat1
                         equal-area, true scale on lat0 and lat1
          bonne lat0     equally spaced parallels, equal-area, paral-
                         lel lat0 developed from tangent cone

          Projections with bilateral symmetry about the Prime Meridian
          and the equator.

          polyconic      parallels developed from tangent cones,
                         equally spaced along Prime Meridian
          aitoff         equal-area projection of globe onto 2-to-1
                         ellipse, based on azequalarea
          lagrange       conformal, maps whole sphere into a circle
          bicentric lon0 points plotted at true azimuth from two cen-
                         ters on the equator at longitudes ±lon0,
                         great circles are straight lines (a stretched
                         gnomonic )
          elliptic lon0  points plotted at true distance from two cen-
                         ters on the equator at longitudes ±lon0
          globular       hemisphere is circle, circular arc meridians
                         equally spaced on equator, circular arc par-
                         allels equally spaced on 0- and 90-degree
                         meridians
          vandergrinten  sphere is circle, meridians as in globular,
                         circular arc parallels resemble mercator

          Doubly periodic conformal projections.

          guyou          W and E hemispheres are square
          square         world is square with Poles at diagonally
                         opposite corners
          tetra          map on tetrahedron with edge tangent to Prime
                         Meridian at S Pole, unfolded into equilateral
                         triangle
          hex            world is hexagon centered on N Pole, N and S
                         hemispheres are equilateral triangles

          Miscellaneous projections.

          harrison dist angle
                         oblique perspective from above the North

     Page 5                       Plan 9             (printed 3/28/24)

     MAP(7)                                                     MAP(7)

                         Pole, dist earth radii from center of earth,
                         looking along the Date Line angle degrees off
                         vertical
          trapezoidal lat0 lat1
                         equally spaced parallels, straight meridians
                         equally spaced along parallels, true scale at
                         lat0 and lat1 on Prime Meridian
                         lune(lat,angle) conformal, polar cap above
                         latitude lat maps to convex lune with given
                         angle at 90oE and 90oW

          Retroazimuthal projections.  At every point the angle
          between vertical and a straight line to `Mecca', latitude
          lat0 on the prime meridian, is the true bearing of Mecca.

          mecca lat0     equally spaced vertical meridians
          homing lat0    distances to Mecca are true

          Maps based on the spheroid.  Of geodetic quality, these pro-
          jections do not make sense for tilted orientations.  For
          descriptions, see corresponding maps above.

          sp_mercator
          sp_albers lat0 lat1

     EXAMPLES
          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) up.  The job can be done
               faster by limiting the map so as not to `plot' the
               invisible part of the world: `map perspective 1.025 -o
               40.75 74 -l 20 60 30 100'.  A circular border can be
               forced by adding option `-w 77.33'.  (Latitude 77.33°
               falls just inside a polar cap of opening angle arc-
               cos(1/1.025) = 12.6804°.)

          map mercator -o 49.25 -106 180
               An `equatorial' map of the earth centered on New York.
               The pole of the map is placed 90o away (40.75+49.25=90)
               on the other side of the earth.  A 180° 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 map mercator -o
               130.75 74

          map albers 28 45 -l 20 50 60 130 -m states
               A customary curved-latitude map of the United States.

          map harrison 2 30 -l -90 90 120 240 -o 90 0 0
               A fan view covering 60° on either side of the Date
               Line, as seen from one earth radius above the North

     Page 6                       Plan 9             (printed 3/28/24)

     MAP(7)                                                     MAP(7)

               Pole gazing at the earth's limb, which is 30° off ver-
               tical.  The -o option overrides the default -o 90 0
               180, which would rotate the scene to behind the
               observer.

     FILES
          /lib/map/[1-4]??  World Data Bank II, for -f
          /lib/map/*        maps for -m
          /lib/map/*.x      map indexes
          /bin/aux/mapd     Map driver program

     SOURCE
          /sys/src/cmd/map

     SEE ALSO
          map(6), plot(1)

     DIAGNOSTICS
          `Map seems to be empty'-a coarse survey found zero extent
          within the -l and -w bounds; for maps of limited extent the
          grid resolution, res, or the limits may have to be refined.

     BUGS
          Windows (option -w) cannot cross the Date Line.  No borders
          appear along edges arising from visibility limits.  Segments
          that cross a border are dropped, not clipped.  Excessively
          large scale or -d setting may cause long line segments to be
          dropped.  Map tries to draw grid lines dotted and -t tracks
          dot-dashed.  As very few plotting filters properly support
          curved textured lines, these lines are likely to appear
          solid.  The west-longitude-positive convention betrays Yan-
          kee chauvinism.  Gilbert should be a map from sphere to
          sphere, independent of the mapping from sphere to plane.

     Page 7                       Plan 9             (printed 3/28/24)