SMAP(1) Smap Manual SMAP(1)
NAME
smap - simple world maps
SYNOPSIS
smap [ -d gshhgdir ] [ -lat lat ] [ -lon lon ] [ -z zoom ] [ -w width ]
[ -h height ] [ -p proj ] [ -R res ] >output.ppm
DESCRIPTION
Smap reads GSHHG [1] map data from disk and plotting commands from
stdin and writes a PPM image of the requested world map to stdout.
The options are
-d Read GSHHG data from gshhgdir (/var/data/geo/gshhg/latest).
-lat, -lon
Centre at lat,lon (0.0, 0.0).
-z Set zoom level (1.0).
-w, -h Set output dimensions in pixels (640, 400).
-p Apply cartographic projection: equirect, mercator, gall-peters,
or hammer (e).
-R Set resolution, as defined in GSHHG documentation [1]: full,
high, intermediate, low, or crude (c).
Smap waits until it receives EOF on stdin before writing a PPM image to
stdout. Commands issued via stdin must be of the form:
keyword|param1|param2|...
(no space is allowed around the delimiter character). The following
commands are currently supported:
map|category|level
Draw map boundaries, where category is one of shores, rivers, or
borders, and level is the detail level up to which shapes are
plotted (as described in GSHHG documentation [1]).
mark|lat|lon|size|type|R|G|B
Place a marker at given coordinates, where lat and lon are in
degrees, size is in pixels, type is one of 0 (plus), 1 (cross),
2 (square), or 3 (diamond), and R, G, and B are colour values
between 0 and 255.
text|lat|lon|string|fontid|pos|R|G|B
Place a text label specified by string at given coordinates,
where the label may contain ASCII characters as well as \n for
newline and \\ for backslash. Fontid identifies the font by one
of the integer values 0 (bold8x16), 1 (vt220iso8x8), or 2
(gomono12x23) (0). Pos is an integer that specifies the anchor
position with possible values 0 (centre), 1 (upper left), 2
(upper right), 3 (bottom left), or 4 (bottom right). The rest of
the parameters are as in earlier commands.
icon|lat|lon|iconfile|pos|R|G|B
Place an icon at given coordinates, where iconfile is the path
to a binary PBM (1-bit) or PGM (8-bit) image and the other
parameters are as in earlier commands.
line|lat0|lon0|lat1|lon1|sty|R|G|B
Draw a line between given coordinates, where sty is an integer
specifying the line style with currently only a single possible
value: 0 (solid), and the other parameters are as before.
BUILDING
Build with (Net)BSD make(1). This also builds and links shapelib [4]
(external/shapelib) using its own build mechanism.
External code dependencies are shapelib and some fonts that are all
included under external/ for convenience.
Data dependencies may be downloaded using the helper script
scripts/fetchdata.sh.
EXAMPLES
The file examples/demo.smap contains commands to generate a simple map
as follows:
cat examples/demo.smap | ./smap -z 3 -R i >demo.ppm
The included script scripts/geogrep can be used to produce smap com-
mands to plot a wide variety of locations of interest based on GeoNames
[2] data, which can be downloaded and prepared (unzip(1)ped, split by
class, and gzip(1)ped) using the helper script scripts/fetchdata.sh
(splitting the data by class is not strictly necessary as
scripts/geogrep can and does fall back onto the whole dataset when it
cannot find or use the splits, but it does speed up lookups consider-
ably at the expense of extra storage).
The example script examples/famous_tree.sh demonstrates how
scripts/geogrep can be combined with smap, by using it to find and gen-
erate maps of famous trees in a specified country. It can be invoked
thus:
cd examples && ./famous_trees.sh NZ
SEE ALSO
xrmap(1x)
HISTORY
The first version of smap used a slightly different syntax for commands
and could not display icons. The next version added a new primitive
for icons, as well as considerable code and complexity to process and
display GeoNames data via a (now defunct) loc keyword. The latter were
subsequently removed in favour of using the supplied scripts/geogrep
script to generate primitive smap commands to mark desired GeoNames
locations.
AUTHOR
Pouya Tafti <pouya@nohup.io>
LICENCE
See LICENCE for the main code and individual licences under external/
for included third-party code.
BUGS
There likely are quite a few.
Handling of 1-bit PBM icons is somewhat buggy.
REFERENCES
[1] GSHHG, A Global Self-consistent, Hierarchical, High-resolution
Geography Database <https://www.soest.hawaii.edu/pwes-
sel/gshhg/>.
[2] GeoNames <https://www.geonames.org/>.
[3] GeoNames Feature Codes <https://www.geon-
ames.org/export/codes.html>.
[4] Shapelib, Shapefile C Library <http://shapelib.maptools.org/>.
Smap 15 February 2022 SMAP(1)