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).

-h  Display a brief help page, then terminate.

-v  Display the version of code.

-language id
    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.

-projection number
    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).

-width number
    The width of the image to generate, in pixels.

-height number
    The height of the image to generate, in pixels.

-zoom number
    Zoom level of the Earth. Default is 1, which shows the whole Earth adjusted to the window size.

-aspect number
    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.

-inclination number
    Produce a map with given inclination of the Equator with respect to horizontal direction (value in degrees).

-latitude number
    Select point of given latitude as the center of map (Latitude value in degrees, + for North, - for South). Default latitude is 0 degree.

-longitude number
    Select point of given longitude as the center of map (longitude value in degrees, + for East, - for West). Default longitude is 0 degree.

-search location
    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.

-field number
    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.

-field location
    Select coordinates of 'location' to be the center of the map. Default is void location (no search performed at startup).

-gspacing number
    Specify the grid spacing (in degrees) between consecutive meridians or parallels.

-gslat number
    Specify the grid spacing (in degrees) between consecutive parallels.

-gslon number
    Specify the grid spacing (in degrees) between consecutive meridians.

-marksteps t_1,t_2,t_3,t_4,t_5
    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).

-namesteps t_1,t_2,t_3,t_4,t_5
    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).

-peakmarks s_1,s_2,s_3,s_4,s_5
    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...)

-peaksizes p_1,p_2,p_3,p_4,p_5
    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.

-citymarks s_1,s_2,s_3,s_4,s_5
    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...)

-citysizes p_1,p_2,p_3,p_4,p_5
    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.

-cityfilter specification
    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.

-locfilter specification
    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.

-rcfile filename
    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.

-mapfile filename
    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'.

-locfile filename
    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'.

-outfile filename
    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.

-ppmoutput
    Write a PPM image at startup (after reading the config files and command line options) and exit xrmap afterwards, without entering into the GUI.

-xpmoutput
    Write a XPM image at startup (after reading the config files and command line options) and exit xrmap afterwards, without entering into the GUI.

-psoutput
    Write a PostScript image at startup (after reading the config files and command line options) and exit xrmap afterwards, without entering into the GUI.

-preview time
    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.

-pswidth value
    Set width of the PostScript output, in millimeters.

-pslmargin value
    Set width of the left margin of the PostScript output, in millimeters.

-psbmargin value
    Set height of the bottom margin of the PostScript output, in millimeters.

-psrot angle
    Rotate the PostScript output by <angle>. This parameter can only take values 0,90 or -90.

-pscolor
    Use color for PostScript output (default).

-psgrayscale
    Use color for PostScript output.

-psviewer name
    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.

-imviewer name
    Select the generic image viewer (display, from the ImageMagick package, by default).

-printcmd string
    Specify the printing command (lpr -Plocal by default).

-editor string
    Specify the command line of the text editor (emacs by default).

-continent list
    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.

-category list
    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.

-hierarchy abcde
    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.

-color i,±colorname
    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.

-font i,fontname
    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.

-menu
    Start xrmap in menu mode, with just a blank image and no map shown.

-reverse
    Reverse the colors (white and black exchanged and so on).

-resetcolors
    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.

±compress
    Use (+) or do not use (-) gzip compression for output files. Default is no compression (-).

±tropics
    Display (+) or do not display (-) tropics/equator/polar circles on the map. By default they are drawn in brown4.

±gridlines
    Display (+) or do not display (-) gridlines on the map. By default they are drawn in orange, spaced at 15 degrees.

±earthcontour
    Display (+) or do not display (-) the Earth contour on the map. By default it is displayed.

±cities
    Display or do not display cities (from the system wide or user specified -locfile) on the map. By default they are.

±peaks
    Display or do not display mountain peaks (from the system wide or user specified -locfile) on the map. By default they are.

±locations
    Display or do not display names of other locations (from the system wide or user specified -locfile). By default they are not.

±placename
    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.

±transparent
    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.

International Boundaries [INT]
    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, Islands and Lakes [CIL]
    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.