Table of Contents
xrmap - Maps portions of the Earth from vector map datalongitude/latitude
info
xrmap +cities -zoom 20 -category all -latitude 45 -longitude
-80 -continent all -projection 3
-color "riv2,+blue"
This manual page documents the X11 xrmap program. Xrmap is
a GIS (Geographic Information System) 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. Features include coast lines, political
boundaries, rivers, lakes, glaciers, canals, major cities, major airports,
mountain peaks, etc. 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 for instance the selection of
geographic features to be displayed and their colors. In addition to the
standard Spherical projection, Xrmap implements Rectangular, Cylindrical,
Mercator, Miller, Sinusoidal, Elliptic and Mollweide projections. All parameters
can be adjusted interactively from the builtin mouse driven menu, or from
the command line, or by editing a script. Up to some extent, the maps can
be edited or enriched by user defined features (pixmaps, labels, etc). Xrmap
includes extensive geographic or political data (as well as flags, hymns,
anthems, etc) concerning all world countries. For the larger part, these
data are extracted from the CIA World Fact Book, which is in the public
domain.
Xrmap was originally derived from the earlier program 'rmap' by Reza
Naima, a console mode program capable of producing png, jpeg or gif images
of the Earth form the CIA World Data Base. However, xrmap now has many
more features.
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).
- -accuracy number
- Set the value of the
accuracy parameter. When the value is smaller, the points interpolating
polygonal lines of the vector map are more densely spread. This produces
more accurate details, at the expense of a longer calculation time. Practical
values are in the range 0.1 ... 10.0, with 1.0 being the default value.
- -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.
- -coordinates xy
- Specifies how coordinates of grid lines (meridians,
parallels) should be written on the map. If xy=00, nothing is drawn; if
xy=LB, latitudes are written on the Left and longitudes at the Bottom. The
xy string should have exactly two letters, valid letters are 0=none, L=left,
R=right, T=top, B=bottom. Default is 00.
- -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 400,3000,8000,15000,25000 (for instance, names of objects of
magnitude 1 and 2 will appear if the zoom is set to 4 and the window width
is larger than 800, since 4*800 >= 3000).
- -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.
- -define feature_definition
- Each 'define' creates a new
feature to be linked with a geographic position in xrmap. This can be a
pixmap, a polygonal line or region, an ellitic region, a system call,
a new text label or a modification of an existing label, etc. All defines
are ranked according to the order in which they have been set. A priori,
the list of defines is empty. This option is provided as a way to introduce
user defined objects or system calls. The -secure option is there to disable
system calls (for obvious security reasons).
- -undefine rank
- This cancels
the feature of the given rank (if any).
- -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, PostScript or RcFile format, and corresponding file
suffixes .ppm, .xpm, .ps, .eps or .rc 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 compress the output whenever option
+compress is set. 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.
- -pixmap destination|filename
- Sets X pixmap file
'filename' to destination. Destination is one of: data (data window background),
cmd (command window background), button0, button1, button2 (buttons in
mode 0=normal, 1=highlighted, 2=pressed). 'filename' should point to a XPM
file, or possibly a .xpm.gz gzipped XPM file.
- -theme filename
- Loads theme
file 'filename', so that the color menus and backgrounds can be changed randomly.
If 'filename' is not an absolute path, then xrmap searches 'filename' in the
current directory, and if it is not found, then looks in the systemwide
SHAREDIR/themes subdirectory.
- -ppmout
- Write a PPM image at startup (after
reading the config files and command line options) and exit xrmap afterwards,
without entering into the GUI.
- -xpmout
- Write a XPM image at startup (after
reading the config files and command line options) and exit xrmap afterwards,
without entering into the GUI.
- -epsout
- Write an Encapsulated PostScript
file at startup (after reading the config files and command line options)
and exit xrmap afterwards, without entering into the GUI.
- -psout
- Write
a PostScript image at startup (after reading the config files and command
line options) and exit xrmap afterwards, without entering into the GUI.
- -rcout
- Read the config files and command line options, output those parameters
and the other defaults in RcFile format and exit xrmap afterwards, without
entering into the GUI.
- -preview time
- In the -ppmout, -xpmout, -epsout, -psout,
-rcout modes, preview the corresponding image during 'time' (expressed in
seconds), before exiting the program. The default is not to preview the
image.
- -arc read|filename
- Read 'filename' as arcinfo data. There are also some
other exotic suboptions to deal with arcinfo data. Chech the ARCINFO file
for more details.
- -dump write|filename
- Dump the vector map data into 'filename',
and exit xrmap. If the -category and -continent options are set, only the
data which are matching the selection will be dumped. The data can be dumped
either in JPD format (dafault), or in ASCII format. These choices can be
specified by -dump JPD or -dump ASCII, respectively. The ASCII output is
more or less arcinfo-compatible, and can be fed back to xrmap via the option
'xrmap -arc read|XXX'.
- -pswidth value
- Set width of the PostScript output, in
millimeters.
- -pslinewidth value
- Set line width of the PostScript output,
in PostScript points (1/72 inch).
- -psleftmargin value
- Set width of the left
margin of the PostScript output, in millimeters.
- -psbottommargin value
- Set
height of the bottom margin of the PostScript output, in millimeters.
- -psrotate
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).
- -musicplayer string
- Specify the command line of the music player, used
to play National hymns (timidity by default, with default music format
MIDI).
- -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..34 for Earth/Gridline colors,
i=35..42 for Mark/Label colors, i=43..51 for Menu/widget colors (foreground/background
of text menus, widgets, 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, ear, lab, mnu (which have respective offsets int->0,
nat->3, riv->5, cil->16, ear->28, lab->35, mnu->45) e.g. int2=2, nat1=4, riv3=8, cil5=21,
lab6=41.
- -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
type
- Start xrmap in menu mode 'type', specified as one character. Then xrmap
just loads a blank image and does not show any map.
- -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.
- -ranking
- Recalculate the country/continent/worldwide
ranks of cities and peaks, and output the result to stdout. This is useful
in case more entries have been added in the list, so that the ranks have
to be recalculated.
- ±dms
- Use (+) or do not use (-) degree-minute-second mode
for the output of angle values. If -dms is set, angles are shown with 3 decimal
places.
- ±memory
- Store (+) or do not store (-) the vector map in RAM. Storing
the vector map in RAM requires 10 Mbytes of memory and speeds up a little
bit xrmap's operation.
- ±secure
- Set (+) or unset (-) secure mode. Under the
secure mode, user defined system calls (such as those set via -define "exec|...")
are disabled. Default is "unsecure" mode, which allows e.g. to use xrmap as
a presentation tool.
- ±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. Option ++cities
displays also city names. Default is +cities.
- ±airports
- Display or do not
display airports (from the system wide or user specified -locfile) on the
map. Option ++airports displays also airport names. Default is -airports.
- ±observatories
- Display or do not display observatories (from the system
wide or user specified -locfile) on the map. Option ++observatories displays
also observatory names. Default is -observatories.
- ±peaks
- Display or do not
display mountain peaks (from the system wide or user specified -locfile)
on the map. Option ++peaks also displays peak names. Default is +peaks.
- ±locations
- Display or do not display names of other locations (from the system wide
or user specified -locfile). Default is -locations.
- ±placename
- Vary (or do
not vary) the position of the city name according to the position 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. Default is -placename.
- ±smartlabels
- When
+smartlabels is set, any label that would overlap a label previously drawn
on the map is omitted. This requires a small amount of additional memory,
and is the default. The option is disabled when -smartlabels is set.
- ±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.
Xrmap
has internal keyboard shortcuts that allow to change interactively most
of the settings. These shortcuts are:
! ? M F D S O C N H V Q I A B
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', 'N' open respectively the general
menu, the file menu, the command menu, the search menu, the option menu,
the color menu, the map edition 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', 'A', 'B', 'P' 'L', 'E', 'G', 'T' are toggles to be used
to show or not to show cIties, Airports, oBservatories, 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. Key '&' saves the map as an encapsulated
PostScript file and loads it into a PostScript viewer for printing. Key
'*' exports the parameters into a .rc file, in a format which can be fed back
to xrmap through a command line 'xrmap -rcfile xyz.rc' Space or escape keys
can be used to erase the top and bottom text mentions.
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) +air(ports) -air(ports)
+obser(vatories) -obser(vatories)
+pea(ks) -pea(ks) +l(ocations) -l(ocations)
+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>
gspacing <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.
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]
Earth/Grid features [ear]
Background color of map [28]
Background color of sky [29]
Foreground color of stars [30]
Color of Equator, Tropics and Polar circles [31]
Color of Parallel gridlines [32]
Color of Meridian gridlines [33]
Color of Earth contour [34]
Marks and labels [lab]
Color of circular city marks [35]
Color of text of city names [36]
Color of symbols representing airports [37]
Color of text of airport names [38]
Color of symbols representing observatories [39]
Color of text of observatory names [40]
Color of triangles representing peaks [41]
Color of text of peak names [42]
Color of text of location labels (land) [43]
Color of text of location labels (water) [44]
Menu/Widget colors [mnu]
Foreground color of text menus [45]
Background color of text menus [46]
Foreground color of text caret [47]
Background color of command window [48]
Background color of Escape button [49]
Foreground color of triangular ticks [50]
Color of cross representing a marked point [51]
Foreground color of the selection rectangle [52]
Foreground color of the current selected point [53]
Jean-Pierre Demailly <demailly@ujf-grenoble.fr>
Xrmap is loosely
derived from 'rmap' by Reza Naima <reza@reza.net> It no longer shares much code
with the original program.
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.
Table of Contents