Short description of program
============================

Xrmap is an GPL'd user-friendly X program which can be used to generate 
accurate images of small or bigger portions of the Earth. The main data
source is the CIA World Data Bank II, a huge geodata set available from
   ftp://sepftp.stanford.edu/pub/World_Map/ 
   ftp://gatekeeper.dec.com/pub/graphics/data/cia-wdb 
and
   http://www.evl.uic.edu/pape/data/WDB/
The data were produced by the US government during the 1980s.

The CIA_WDB2 consists of vector descriptions of coastlines and islands, 
political boundaries, major and minor rivers, glaciers, lakes, canals, 
reefs, etc. The accuracy of the data is at best 1" of arc, approximately 
30 meters at the Equator -- in fact all recorded points are given by
integer coordinates representing seconds of arc.

In practice, the images produced by Xrmap have a resolution of about
0.5 km in most parts of the Earth, and therefore they can be accurately 
zoomed in, up to a factor of 100 or more. The Xrmap package also 
exploits a rather comprehensive data set of world cities and locations - 
about 20000 cities are listed.

When clicking on a city, related data appear in a popup window -- such as 
local time, administrative region, national and regional flags, etc. 

The earlier Xrmap-1.x was originally derived from the rmap console utility 
by Reza Naima (http://www.reza.net/rmap/)

Since then, Xrmap has evolved on its own, and therefore no longer
shares much of its code with rmap. Version 2.x has many more features
than the original 'rmap', especially it implements 8 different
projection modes in total (Spherical, Rectangular, Cylindrical,
Mercator and Miller, Sinusoidal, Elliptic and Mollweide), as well as 
a reverse search of coordinates. All parameters, colors and
configuration can be set interactively from the GUI. Xrmap supports
writing images in ppm, xpm, ps or compressed ppm.gz, xpm.gz, ps.gz
formats. It can also produce images without entering into the GUI,
since most parameters can alternatively be set via the command line
options (still, xrmap requires the X environment to do so, in contrast
with rmap).

Compilation and installation
============================

1) Introduction

There are 2 options: compiling xrmap with or without the libz library 
support. The libz library allows xrmap to read the compressed map
CIA_WDB2.jpd.gz (7 MB) instead of the uncompressed CIA_WDB2.jpd (11.5 MB) 
- at the expense of being a bit slower then. The main interest of 
the libz option, however, is that xrmap will save images as compressed
ppm.gz, xpm.gz ps.gz images, which may occupy up to 100 times less disk 
space than their uncompressed counterparts - usually only a few dozens 
of kB. Other image formats can be obtained with well known conversion
tools, such as the Netpbm or ImageMagick packages.

The libz support is set by default and can be unset by removing the 
-DZLIB compilation option in the Makefile or Imakefile.

2) Quick install:
   xmkmf
   (or copy the included Makefile.noimake to Makefile)
   make
   make install  (as root)
   make clean

3) If you don't have it already, you'll need the CIA vector data.
   Download  CIA_WDB2.jpd.gz from
      ftp://ftp.ac-grenoble.fr/ge/geosciences/CIA_WDB2.jpd.gz
   or from
      http://
   The compressed file is about 7 MBytes. Those folks who already
   downloaded the REZ file can convert it to the JPD format by means 
   of the 'rez2else' utility. See README.rez from the  tools/rez2else/
   subdirectory. Those who wish to do so can also produce directly
   the JPD file from the original CIA "cobal data" (.cbd), thanks to 
   the 'cbd2else' utility in the tools/cbd2else/ subdirectory.

4) Decompress the vector map and install it as 
      /usr/share/rmap/CIA_WDB2.jpd
   The decompressed file is about 11.5 Mbytes, exactly 12037424 bytes.
   As explained earlier, Xrmap can also use the *compressed* file and 
   decompress it on the fly during the execution. The speed of 
   calculation then suffers a little - not so much in fact if you have 
   a resonably fast processor (but then you probably also have a huge 
   hard disk, so that you can hopefully afford spoiling 5 additional 
   Mbytes for the sake of having Xrmap running faster...)

   You may of course install it elsewhere, especially if you have 
   modified the SHAREDIR setting before compiling... Xrmap can
   anyway read the data from any place (thanks to the -mapfile option).

5) Try out ./xrmap and any other variations you would like.
   (the xrmap help is obtained by typing xrmap -h)

6) Xrmap's parameters can be adjusted either from the command line,
   from the builtin GUI or from the user's private configuration file
   ~/.xrmaprc. Colors and features are set as in the Xrmaprc system
   wide default. After this optional part, which can be empty (thus 
   keeping the system wide default colors), one can start adjusting 
   the other parameters as follows:

<commandlines>
-z 4 -lat 51.5 -lon 9 -p 0

or
<commandlines>
-search Paris

   if you want to see (say) Western Europe in spherical mode. Options
   can be set on the same lines or on different lines, provided that
   parameters associated with an option are on the same line. Check
   'example.xrmaprc' to see an example.

7) The CIA_WDB2 data can be used to build vector maps in the VMF format 
   used by sunclock (check Freshmeat or 
      ftp://ftp.ac-grenoble.fr/ge/geosciences/ )
   The script tools/jpd2else/buildvmf provides an example (the resulting 
   map is compatible only with sunclock-3.50pre1 and over).

Notice concerning the JPD format
================================

The binary format of the CIA world data bank II used with xrmap-2.x
is the "JPD format" described in the 'tools/jpd2else' subdirectory.
It is no longer compatible with the REZ format (used by rmap and
xrmap-1.x). However, the earlier .rez file can be converted to the
newer JPD format by means of the 'rez2else' utility from the 
tools/rez2else/  subdirectory.

Copyright
=========

Xrmap is released under the GPL (see COPYING for details). The associated
data have been obained from sources stating that the data can be freely
copied and reproduced, some of them requiring in addition that the
source be mentioned. Here they are :

Acknowledgment
==============

As mentioned above, the CIA World Data Bank II is available from
   ftp://sepftp.stanford.edu/pub/World_Map/ 
   ftp://gatekeeper.dec.com/pub/graphics/data/cia-wdb 
and is public domain.

The CIA factbook is a huge set of geopolitic data concerned all world
countries. It is updated every year, and is available from
   http://www.cia.gov/cia/publications/factbook/

Nice PDF maps of world continents are also available from the above site.
Individual PDF maps of the world countries can be found on the
United Nations Cartographic site
   http://www.un.org/Depts/Cartographic/english/htmain.htm
   
The huge data set of cities and their coordinates as well as the 
collection of national flags were obtained courtesy of 
   http://www.gazetteer.de/
(which no longer mentions any visible copyright). Some complementary flags
(e.g. the Canadian and Australian provincial flags) were obtained from
   http://www.fotw.ca/flags
which states "these pages are offered freely to the Internet community",
the explicit copyright being detailed in the 'disclaim.html' document there.
Bigger state flags for the USA were obtained from
   http://www.50states.com/
which states "all files are believed to be in the public domain".

The altitudes were taken from http://www.calle.com/  and/or calculated
from the GTOPO30, GLOBE or ETOPO2 topographic data, which are freely
available on the web from the USGS and NOAA sites:

GTOPO30: ftp://edcftp.cr.usgs.gov/pub/data/gtopo30/global/
GLOBE: http://www.ngdc.noaa.gov/seg/topo/gltiles.shtml
ETOPO2: ftp://topex.ucsd.edu/pub/global_topo_2min/

The list of peaks and mountains is taken from various sites and references
including:
   http://www.peakware.com/encyclopedia/peaks
   http://www.highalpex.com/Peaklist/
   http://www.summitpost.com/

The timezone data are extracted from:
   ftp://elsie.nci.nih.gov/pub/tzdata2001d.tar.gz
which seems to be public domain (no copyright mention).

The National anthems and hymns have been extracted from our Windoze
competitor, the AmiGlobe program by Olivier Collard
   http://www.amiglobe.com
Although AmiGlobe is Shareware, these files are themselves in the 
public domain (and available from other sources than the AmiGlobe site). 

These data retain their original copyright when unmodified, and the GPL 
applies wherever possible to the modified data sets included here.

MIDI player stuff
=================

The MIDI files (of the National Hymns) can be played with the excellent 
MIDI player 'TiMidity' which is available from
   http://www.goice.co.jp/member/mo/timidity/

You'll need also the Gravis Ultra Sound music samples (EAW patches), on one
of the sites
   http://www.dtek.chalmers.se/~d95mback/eawpats/
   http://www.stardate.bc.ca/eawpatches/html/default.htm
   ftp://urano.iceb.ufop.br/pub/timidity

See the ./midi_cfg subdirectory for more details about installing TiMidity.

Jean-Pierre Demailly <demailly@ujf-grenoble.fr>
January 26, 2003
