simple world maps
5cba955f2625 — pouya@nohup.io default tip 9 months ago
rename geogrep.sh to geogrep
5dc34e9b83e7 — pouya@nohup.io 9 months ago
add examples/grid.sh
50d02a854391 — pouya@nohup.io 9 months ago
wrapping is now done properly instead of using hacks

heads

tip
browse log

clone

read-only
https://hg.sr.ht/~pdt/smap
read/write
ssh://hg@hg.sr.ht/~pdt/smap
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)