XRMAP(1)

NAME
xrmap - Maps portions of the Earth from longitude/latitude info

SYNOPSIS

  xrmap +cities -zoom 20 -category all -latitude 45 -longitude -80
        -continent all -projection 3 -color "riv2,+blue"

DESCRIPTION
This manual page documents the X utility xrmap. Xrmap is a small program that can read a custom format of the CIA world data bank II global vector information to generate images of the Earth under the X Window system. The images can be very accurately zoomed in, up to a factor of 100 or more. There is a variety of options and parameters to control the output of the image, including the selection of geographic features to be displayed and their colors. All parameters can be adjusted interactively either from the builtin command line widget or from the mouse. Xrmap is derived from the earlier program 'rmap' by Reza Naima, a similar (console mode only) program capable of producing png, jpeg or gif images rather than displaying the map in a X window. On the whole, xrmap has many more features, especially it implements Rectangular, Cylindrical, Mercator, Miller, Sinusoidal, Elliptic and Mollweide projections in addition to the standard Spherical projection.

OPTIONS
The following options are available. They can be abbreviated to 1,2 or 3 letters following the - (or +) sign, whenever the abbreviation is not ambiguous. A double minus sign (--) is equivalent to a single one (minus signs are not required when the options are entered in X mode from the builtin command line). Display a brief help page, then terminate. Display the version of code. Sets the file of menu dialog messages to be xrmap_msg.id, where id is the standard 2-letter identificator of a language. The default language is set from the environment LANG parameter, and falls back to English if the corresponding language is not available in the xrmap distribution. Select the type of projection. Possible numbers are 0=Spherical, 1=Rectangular, 2=Cylindrical, 3=Mercator, 4=Miller, 5=Sinusoidal, 6=Elliptic, 7=Mollweide. Projection types 2, 5, 7 are area preserving, while 3 (Mercator) is conformal (angles are preserved, but not areas nor lengths). Sperical projection is by definition invariant by rotation and is very accurate under large zoom values. The other types don't preserve anything (although Elliptic approximately preserves areas with maximal error 8% by excess near the Equator). The width of the image to generate, in pixels. The height of the image to generate, in pixels. Zoom level of the Earth. Default is 1, which shows the whole Earth adjusted to the window size. Value of the aspect factor (= ratio height/width in modes other than Spherical). Default is 1. Larger values will stretch the map in the vertical direction. The option has no effect in Spherical mode. Produce a map with given inclination of the Equator with respect to horizontal direction (value in degrees). Select point of given latitude as the center of map (Latitude value in degrees, + for North, - for South). Default latitude is 0 degree. Select point of given longitude as the center of map (longitude value in degrees, + for East, - for West). Default longitude is 0 degree. Select coordinates of 'location' to be the center of the map. Default is void location (no search performed at startup). If several identical or different names match the location request (e.g. when a wildcard) has been used, xrmap pops up a selection window at startup. Select the number of the field to be searched (1=name(default), 2=country, 3=region). This takes effect only when a search is performed. Select coordinates of 'location' to be the center of the map. Default is void location (no search performed at startup). Specify the grid spacing (in degrees) between consecutive meridians or parallels. Specify the grid spacing (in degrees) between consecutive parallels. Specify the grid spacing (in degrees) between consecutive meridians. Set the values of "thresholds" t_i for the virtual size of the Earth (i.e., the actual width of the window multiplied by the zoom factor), above which markers of objects of magnitude i become visible (see below). Normally the t_i is an increasing sequence of integers, by default 150,1200,3000,6000,10000 (for instance, objects of magnitude 1 and 2 will appear if the zoom is set to 1.5 and the window width is larger than 800, since 1.5*800 >= 1200). Set the values of "thresholds" t_i for the virtual size of the Earth (i.e., the actual width of the window multiplied by the zoom factor), above which names of objects of magnitude i become visible (see below). Normally the t_i is an increasing sequence of integers, by default 625,5000,12500,25000,40000 (for instance, names of objects of magnitude 1 and 2 will appear if the zoom is set to 7 and the window width is larger than 800, since 7*800 >= 5000). Set the sizes s_i of marks representing peaks of magnitude 1,2,3,4,5 (by decreasing importance). A size s_i equal to 0 means that the peaks of magnitude i will not appear. If one sets e.g. -peakmarks 3,3,3,3,3 all peaks - whatever their magnitude - will be attributed a mark of magnitude 3. If one sets -peakmarks 5,4,3,2,1 the size of the mark will be inversely proportional to the magnitude of the city (just to give a stupid example...) Specify the height over which a peak will be considered as of magnitude 1,2,3,4,5 respectively by decreasing importance. The default values are p_1=3000000, p_2=700000, p_3=300000, p_4=100000, p_5=1. Set the sizes s_i of marks representing cities of magnitude 1,2,3,4,5 (by decreasing importance). A size s_i equal to 0 means that the cities of magnitude i will not appear. If one sets e.g. -citymarks 3,3,3,3,3 all cities - whatever their magnitude - will be attributed a mark of magnitude 3. If one sets -citymarks 5,4,3,2,1 the size of the mark will be inversely proportional to the magnitude of the city (just to give a stupid example...) Specify the population numbers over which a city will be considered as of magnitude 1,2,3,4,5 respectively by decreasing importance. The default values are p_1=3000000, p_2=700000, p_3=300000, p_4=100000, p_5=1. The specification is a string of at most three characters C,R,* (respectively for Capital cities, Regional capital cities and ordinary cities). Only those cities for which the corresponding category has been set will be shown. The specification is a string of a number of characters among the letters B,C,I,K,L,O,R,S,T,V,* (respectively for Bay/gulfs, Countries, Islands, laKes, Lands, Oceans, Reefs, Seas, sTraits, riVers, others). Only the locations whose type is listed will appear. The path to the configuration rcfile which, among other things, defines the colors of various items that will be displayed, and whether they will be displayed at all. If the -rcfile value is not specified, the system wide Xrmaprc will be parsed first, and the user defined ~/.xrmaprc will be checked in second place if it exists. If the -rcfile value is set the user defined ~/.xrmaprc will be replaced by the specified file. The path to the CIA map vector data file. The default path of this file is specified in xrmap.h and is `SHAREDIR/CIA_WDB2.jpd'. The path to a file containing a list of timezones, cities or locations to display. The default path of this file is specified in xrmap.h, and is `SHAREDIR/Locations'. The name of the file to which an output is to be written. Allowed formats are PPM, XPM or PostScript, and corresponding file suffixes .ppm, .xpm or .ps should then be used (this is crucial since xrmap uses the suffix to determine which format it should use). With the ZLIB compilation option, xrmap will automatically compress the output. If filename is left NULL, xrmap will instead write the data to stdout (if any data are to be written). In that case, the data will *not* be compressed. Write a PPM image at startup (after reading the config files and command line options) and exit xrmap afterwards, without entering into the GUI. Write a XPM image at startup (after reading the config files and command line options) and exit xrmap afterwards, without entering into the GUI. Write a PostScript image at startup (after reading the config files and command line options) and exit xrmap afterwards, without entering into the GUI. In the -ppmoutput or -xpmoutput modes, preview the corresponding image during 'time' (expressed in seconds), before exiting the program. The default is not to preview the image. Set width of the PostScript output, in millimeters. Set width of the left margin of the PostScript output, in millimeters. Set height of the bottom margin of the PostScript output, in millimeters. Rotate the PostScript output by <angle>. This parameter can only take values 0,90 or -90. Use color for PostScript output (default). Use color for PostScript output. Select the PostScript viewer (gv by default). If xrmap has been compiled with the ZLIB option, the PostScript viewer should be able to decompress files on the fly. Select the generic image viewer (display, from the ImageMagick package, by default). Specify the printing command (lpr -Plocal by default). Specify the command line of the text editor (emacs by default). Sets the list of continents for which features are to be shown. Either the word `all' or a list of comma separated numbers/items where 1=(Af)rica, 2=(As)ia, 3=(Eu)rope, 4=N.America (NA), 5=S.America (SA), 6=(Oc)eanic. [In case letters as used, e.g. EU or EUR... for Europe, upper or lower case do not matter, and a longer string will be accepted]. If no option is specified then `all' is assumed. The 6th item (Oceanic) is meant only for labels of seas and oceans, and does not represent a continent in itself. Sets the list of categories for which features are to be shown. Either the word `all' or a list of comma separated numbers where 1=(int)ernational boundaries, 2=(nat)ional state boundaries, 3=(riv)ers, 4=Coasts, Islands, Lakes (cil). [In case letters as used, e.g. RIV for rivers, upper or lower case do not matter, and a longer string will be accepted]. If no option is specified then `all' is assumed. Specify the permutation abcde of 01234, e.g. 34021, which will define the precedence of features: riv=3 will overwrite cil=4, which overwrite cfg=0 which overwrite nat=2 which overwrite int=1 (the result of such an ordering is maybe absurd... just try). The default is 01234. Sets parameters of color[i] in the internal table of items/colors to be displayed. The parameter string ±colorname should be composed optionally of a sign + or - followed (without any blank space) by a color specification. The sign is a flag specifying whether the item will be displayed or not, and the color is of course the color in which the item will be drawn. The color specification should be either one of the conventional colors from the rgb.txt file, or an hexadecimal value #uvwxyz with 6 places (indicating the three RGB bytes, respectively). The index `i' stands for the type of object (i=0..2 for International boundaries, i=3,4 for National State boundaries, i=5..16 for River types, i=17..27 for Coasts, Islands and Lakes of various types, i=28..38 for Markers/grid/labels colors: background color of map, colors of city markers, gridlines, i=39..43 for Menu/widgets, color of foreground/background of text labels, etc). The precise list of item numbers is explained below. For easier manipulation, the index i can also be specified e.g. as int, nat, riv, cil, mrk, wid (which have respective offsets int->0, nat->3, riv->5, cil->16, mrk->28, wid->38) e.g. int2=2, nat1=4, riv3=8, cil5=21, mrk6=34. Define the i-th font (i=1,2,3,4,5) to be used for cities and locations mentioned on the map, for the magnitude i. Index i=0 is also admitted, and stands for the font used in the builtin menus. Start xrmap in menu mode, with just a blank image and no map shown. Reverse the colors (white and black exchanged and so on). Change the colormap and reset all colors. This is effective (and useful) only in pseudo-color mode, when the colormap is full, for instance after many national flags involving too many colors have been viewed. Use (+) or do not use (-) gzip compression for output files. Default is no compression (-). Display (+) or do not display (-) tropics/equator/polar circles on the map. By default they are drawn in brown4. Display (+) or do not display (-) gridlines on the map. By default they are drawn in orange, spaced at 15 degrees. Display (+) or do not display (-) the Earth contour on the map. By default it is displayed. Display or do not display cities (from the system wide or user specified -locfile) on the map. By default they are. Display or do not display mountain peaks (from the system wide or user specified -locfile) on the map. By default they are. Display or do not display names of other locations (from the system wide or user specified -locfile). By default they are not. Vary (or do not vary) the position of the city name according to the postion of the city on the map. In case the flag is not set, the name always appears above the city mark, on the right. In case the flag is set, the name may appear on the left of the mark, or below, if the mark appears in the right half (resp. upper half) of the window. In Spherical mode, represent (+) or not (-) the continents appearing on the opposite hemisphere, as if the Earth was transparent. By default this option is not set, and it has no effect in non spherical modes.

GUI COMMANDS
Xrmap has internal keyboard shortcuts that allow to change interactively most of the settings. These shortcuts are:
   ! ? M F D S O C H V Q I P L E G T R K < + - <Arrows> <Space> <Escape>
Key '!' enables the command line mode (see below). Key '?' displays the available keyboard shortcuts. Keys 'M', 'F', 'D', 'S', 'O', 'C' open respectively the general menu, the file menu, the command menu, the search menu, the option menu and the color menu.
Key 'H' opens an xterm showing the xrmap manpage, key 'V' shows the version number and date of package, key 'Q' quits the program.
Keys 'I', 'P' 'L', 'E', 'G', 'T' are toggles to be used to show or not to show cIties, Peaks, Locations, Earth contour, Gridlines and Tropics/Equator/Polar circles, respectively.
Key 'R' reverses the colors, key 'K' closes the city/location data window, key '<' recalculates/redisplays the image (xrmap reads again the locfile, so that you can possibly see changes made in that file). Keys '+' and '-' zoom in or zoom out the image by a factor equal to square root of 2. Arrows can be used to change the point at which the map is centered (concurrently with the right mouse button), changing the latitude or longitude by some amount which depends on the zoom factor. Space or escape keys can be used to erase the top and bottom text mentions.

COMMAND LINE MODE
The command line mode allows a more precise and complete handling of the options. The user has to edit the command line, and the modification take place only when <Return> has been pressed (one can also escape the command line mode without taking any action by pressing <Escape>). Several parameters can be set simultaneously. The available abbreviated keys or keywords are
   +ci(ties) -ci(ties) +l(ocations) -l(ocations) +pea(ks) -pea(ks)
   +e(arthcontour) -e(arthcontour) +g(ridlines) -g(ridlines)
   +trop(ics) -trop(ics) +tran(sparency) -tran(sparency)
which are respectively switches for cities, locations, peaks, Earth contour, gridlines, tropics and the transparent mode. Other parameters are set by prescribing
   p <type> w <value> h <value> z <value> a <value>
   f <i,name>
respectively for projection type, width, height of window, zoom, aspect (the aspect parameter is used only in modes other than Spherical), and font of index i;
   lon <value> lat <value> s <value> slat <value> slon <value>
respectively for longitude, latitude (of point at which the map will be centered), and spacing (spacing in latitude or longitude). Categories and continents are set by
   cat(egory) <list> con(tinent) <list> as above. Item colors and display flags can be changed by setting
   col(or) i,(±)colorname
which then attributes color[i]=(±)colorname [See below for the table of items and their indices. Colors can be globally reversed with the single command 'r' or 'rev' or 'reverse' without any parameter.

FEATURES
The following features are available for plotting. To each of these features is associated a color, indexed as color[i], possibly specified e.g. as CIL2, which stands for <start of CIL section>+2. Demarcated or delimited boundary [0]
Indefinite or in Dispute [1]
Other lines of separation of sovereignty on land [2]

National (US) State Boundaries [NAT]
    State boundary lines on land [3]
    State boundary lines on water [4]

Rivers [RIV]
    Permanent major rivers [5]
    Additional major rivers [6]
    Additional rivers [7]
    Minor rivers [8]
    Double lined rivers [9]
    Intermittent rivers - major [10]
    Intermittent rivers - additional [11]
    Intermittent rivers - minor [12]
    Major canals [13]
    Canals of lesser importance [14]
    Canals - irrigation type [15]
    Coasts, major islands and lakes [16]
    Additional major islands and lakes [17]
    Intermediate islands and lakes [18]
    Minor islands and lakes [19]
    Intermittent major lakes [20]
    Intermittent minor lakes [21]
    Reefs [22]
    Salt pans - major [23]
    Salt pans - minor [24]
    Ice Shelves - major [25]
    Ice Shelves - minor [26]
    Glaciers [27]

Basic configuration features [CFG]
    Background color of map [28]
    Color of Equator, Tropics and Polar circles [29]
    Color of Parallel gridlines [30]
    Color of Meridian gridlines [31]
    Color of Earth contour [32]
    Color of circular city marks [33]
    Color of cross representing a marked city [34]
    Color of text of city names [35]
    Color of text of location labels (land) [36]
    Color of text of location labels (water) [37]
    Background color of sky [38]
    Foreground color of stars [39]
    Foreground color of text menus [40]
    Background color of text menus [41]
    Foreground color of text caret [42]
    Background color of Escape button [43]
    Foreground color of triangular ticks [44]

AUTHOR
Jean-Pierre Demailly <demailly@ujf-grenoble.fr>
Xrmap is loosely derived from rmap by Reza Naima <reza@reza.net>

BUGS
Xrmap seems to work pretty well in most cases, however it might still have problems related to incorrect command line options being entered while the program runs (especially, check segfaults or buffer overflows). Xrmap still needs the X environment even when the user merely asked an image output; this is unlikely to be fixed any time soon -- just use 'rmap' if you need to operate without a GUI running, e.g. for web serving.