MAP(1)

💖 MAP 💖

okay so bestie, welcome to the map page from the General Commands Manual — yes, that's the official manual name, and no, we're not gonna be normal about it 💅 this is the part where I tell you what these little icons do, so grab a 🍓 and let's go.

---

✨ NAME ✨

map, mapdemo, mapd — draw maps on various projections 🌈

like, literally the whole point: you want a map? on a projection? pick your fave, we're drawing it 🗺️✨

---

🎀 SYNOPSIS 🎀

so here's the vibe check on how you actually call these things:

map projection [ option ...  ]

mapdemo

okay so map takes a projection and then as many *option*s as your heart desires (that's the [ option ... ] bit — optional, but you can stack 'em) 🫶

and mapdemo? iconic behaviour honestly — it just runs, no args, no notes, main character energy 👑

---

ngl bestie, this is only the start of the page — the descriptions, options and all the juicy bits are coming up next 💖 don't touch that dial!

✨ DESCRIPTION ✨

okay so here's the whole vibe: map writes a map to standard output, and that map is made to be shown off by any of the plotting filters that live in plot(1). cute, right? 💖 And if you hit it with an unknown projection, it doesn't just die on you — it pops a whole menu of projections at you so you can pick one. iconic behaviour tbh. There's also mapdemo, which is basically a short course in mapping if you wanna learn by clicking around. 🎀

By default map gives you world shorelines. That's the base fit. If you want the detailed stuff, -f unlocks data that's classified by feature — like, the deluxe dataset. ✨

🗺️ THE FEATURE FLAGS

• -f [ feature ... ] — pull in more detailed data, sorted by feature.

So the tea on the ranking: features go from rank 1 (that's the default) up to 4, major to minor. And — super important — higher-numbered ranks include all the lower-numbered ones. So rank 4 isn't just the little guys, it comes with the whole family. 🫶

The features are:

• shore[1-4] — seacoasts, lakes, and islands. and heads up: -f always shows shore1, no matter what you asked for. it's non-negotiable, she's always invited. 👑
• ilake[1-2] — intermittent lakes
• river[1-4] — rivers
• iriver[1-3] — intermittent rivers
• canal[1-3] — canals, and 3 means 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)

quick note bestie: in other options, coordinates are in degrees, and north latitude and west longitude are counted as positive. don't get it twisted. 💅

---

🎀 THE OPTIONS 🎀

• -l S N E W — set the southern and northern latitude and the eastern and western longitude limits. Any missing arguments get filled out from the list -90, 90, -180, 180, or from lesser limits suitable to the projection at hand. she'll figure it out. 🌸
• -k S N E W — set the scale as if for a map with limits -l S N E W. and the spicy part: do not consider any -l or -w option in setting scale. like, ignore them completely. 🙈
• -o lat lon rot — orient the map in a nonstandard position, and ngl this one is a whole little imagination exercise. picture a transparent gridded sphere around the globe:
  1. Turn the overlay about the North Pole so that the Prime Meridian (longitude 0) of the overlay coincides with meridian lon on the globe.
  2. Then tilt the North Pole of the overlay along its Prime Meridian to latitude lat on the globe.
  3. Finally, again turn the overlay about its North Pole so that its Prime Meridian coincides with the previous position of meridian rot.

Then project the map in the standard form appropriate to the overlay, but presenting information from the underlying globe. Missing arguments get filled out from the list 90, 0, 0. And 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 longitudes in the tilted, rotated coordinate system. Missing arguments are filled out from the list -90, 90, -180, 180.

fr fr it is wise to give an encompassing -l option with -w. otherwise, for small windows, computing time varies inversely with area! 😭 yes really. tiny window, huge wait. you've been warned.

• -d n — for speed, plot only every *n*th point. speedrun mode. 🔥
• -r — reverse left and right (good for star charts and inside-out views). 🌈
• -v — Verso. switch to the normally suppressed sheet of the map — like the back side of the earth in orthographic projection. the hidden side, the B-side. 💜
• -s1 — superpose. outputs for a -s1 map have no closing.
• -s2 — superpose. outputs for a -s2 map have no opening. the -s1 and -s2 outputs 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). and in the absence of -g, the grid spacing is 10°. ⭐
• -p lat lon extent — position the point lat, lon at the center of the plotting 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. and an extent overrides option -k. 👑
• -c x y rot — after all other positioning and scaling operations have been performed, rotate the image rot degrees counterclockwise about the center and move the center to position 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 the named files. if no files are named, omit map data entirely. names that don't exist as pathnames get 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

also: the environment variables MAP and MAPDIR change the default map and the default directory. ✨

• -b [lat0 lon0 lat1 lon1... ] — suppress the drawing of the normal boundary (the one 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're taken to be the diagonal of a rectangle. and to actually draw that 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 newline. 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 filter supports them.) 🌸
• -y file — the file contains plot(7)-style data for or labels in -t or -u files. each symbol is defined by a comment :name then a sequence of and commands. coordinates (0,0) fall on the plotting point. default scaling is as if the nominal plotting range were commands in file change the scaling. 🧚

---

🗺️ Projections 🗺️

Equatorial projections centered on the Prime Meridian (longitude 0). Parallels are straight horizontal lines.

• mercator — equally spaced straight meridians, conformal, straight compass courses
• sinusoidal — equally spaced parallels, equal-area, same as cylequalarea
• 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 hemisphere and 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(2×colatitude), 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

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, parallel 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 centers on the equator at longitudes ±lon0, great circles are straight lines (a stretched gnomonic)
• elliptic lon0 — points plotted at true distance from two centers on the equator at longitudes ±lon0
• globular — hemisphere is circle, circular arc meridians equally spaced on equator, circular arc parallels 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 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 90°E and 90°W

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 projections 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: a circular border can be forced by adding option (Latitude 77.33° falls just inside a polar cap of opening angle arccos(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 90° 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 Pole gazing at the earth's limb, which is 30° off vertical. 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
• mapd — Map driver program

🌈 SOURCE 🌈

/src/cmd/map

🔥 SEE ALSO 🔥

Go peek at map(7) and plot(1), bestie.

💀 DIAGNOSTICS 💀

If you see Map seems to be empty, that’s the diagnostic being brutally honest: 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 Yankee chauvinism.
• Gilbert should be a map from sphere to sphere, independent of the mapping from sphere to plane.

---

That’s the whole MAP(1) saga, bestie — the source/version and date are chillin’ in the footer, so go say hi to them for me 💖✨