Editing the JPD data file
-------------------------

Starting with version xrmap-2.28, xrmap can edit the JPD vector data.
This is controlled by the options 
  -arc -segment -dump 
(and additionally  -category -continent -mapfile). 

Most of these options work properly only when +memory is set (this is
the default with versions >= 2.30).

Instead of explaining things formally, we instead give a list of examples 
exhausting all possibilities.

1. Loading an ARCINFO file

./xrmap -rcfile rc/Europe.rc -mapfile NONE -arc "read|WDB2_newlines"

Instead of loading the default vector map (CIA_WDB2.jpd), read and load the
(pseudo-)arcinfo file 'WDB2_newlines'; moreover use the rc configuration file
'Europe.rc' from the  rc/ subdirectory. The catch is that ARCINFO files 
are pure ASCII and can be edited by hand -- but they are much slower to parse
than the JPD data. Normally ARCINFO files should be used only for small 
additions to the JPD vector data, or for the purpose of editing the JPD data.

./xrmap -arc "read|russia-central.e00" \
 -arc "lat|60" -arc "lon|110" -arc lambert \
 -arc "scale|1.601E-7" -arc "transl|1.811"

This command will load the arcinfo file 'russia-central.e0' with rather
exotic options (read coordinates as a Lambert projection and convert back
to orthographic coordinates, adjust scale to 1.601E-7 (this is roughly 
what is needed when coordinates are expressed in meters), and translate 
vertically by 1.811 of the Earth radius, starting from the vertex of the 
Lambert conical projection; the standard parallel of the Lambert projection
is 60° North, and the central meridian is 110° East).

Other options are  -arc search (useful for dumping coordinates of an arc
specified with a mouse click) and -arc "precision|8" which sets precision
to 8 decimal places when reading coordinates (default is 6 places).


2. Selecting a segment or a collection of segments

3. Dumping the vector map into a file

The following command line dumps the full WDB2 vector data as a huge 
ASCII file (of about 100 MBytes), under the name 'WDB2_ascii':

xrmap +memory -dump ascii -dump "write|WDB2_ascii"

The following will only dump the data for Europe, respectively the
international border lines for Africa and Europe

xrmap +memory -continent EU -dump ascii -dump "write|WDB2_ascii"
xrmap +memory -continent AF,EU -category INT -dump ascii -dump "write|WDB2_ascii"

To dump into JPD format instead, use -dump JPD. The +memory switch
is used to specify whether preloaded JPD data should be dumped (or not).
Hence +memory is necessary to dump the preloaded JPD data. On the
other hand, it should not be used if an arcinfo file has been loaded 
and you do not want to combine the output of the ARCINFO data with the
JPD data (the JPD data can also be disabled by specifying -mapfile NONE).

Four other available dump options are
  -dump stat       
[output statistics on the total number of arcs that would be dumped]
  -dump split      
[split the huge ASCII output into many smaller files, according to the
type of the arcs, in the range 0...139]
  -dump silent
[turn off the verbose option]
  -dump "precision|8"
[set the output precision to 8 decimal places in ASCII mode]


3. Edition of the vector data

The vector data can be edited using the following method: dump the data 
(or part of it) as an ASCII arcinfo file (possibly with -dump split so as
to get a collection smaller files), edit with an editor or any other
appropriate tool. Load the data back with the -arc option, and finally 
dump them again to JPD format with the -dump JPD switch. OK, this is only
for geeks who know what they are doing !


==============================================================================

Technical specification of the JPD format
-----------------------------------------

The CIA World Data Bank II has been converted to a specifically designed 
format to be used with xrmap-2.0 and over. This format, referred to as
the JPD format, has a simpler encoding than the original Cobal data of 
the CIA Data Bank, and is also slightly more compact (11.5MB instead 
of 12MB for the original binary data, approximately 121MB when expanded
as ASCII data). 

The JPD format is organized as follows. All integers are signed integers
which are encoded either as 
   1 byte (-128<=n<128), 
   3 bytes (-8388608<=n<8388608) or
   4 bytes (-2147483648<=n<2147483648), 
in bigendian order (low weight byte first, big weight byte at the end). 
The unit used for the coordinates is 1 second of arc (1/3600 of degree),
both in longitude (x coordinate) and latitude (y coordinate).

A. First there is a header of 576 bytes

struct header
{
  char magic[12];
  unsigned char maxlength[4];  /* 4-byte integer */
  unsigned char index[560];    /* 140 4-byte integers */
};

The magic string identifies the format. It should be "!JPD1.0\n" completed
with zeroes. The maxlength string is a 4-byte integer indicating the 
maximal length of all segments present in the JPD file. The index 
consists of 140 4-bytes integers indicating the number of segments 
present for each of the 140=5*28 continents*types (5 continents and
28 types = 3 int(ernational) + 2 nat(ional) + 10 riv(er) + 11 cil
(coast-island-lakes) types of segments. They are grouped by continents,
0=africa, 1=asia, 2=europe, 3=north america, 4=south america, with all
28 types being contiguous for each continent. The index[i] i-th value 
is actually the total number of segments of (continent,type)<=i where
i=0..139, so that the last value is the total number of segments.

B. The header is followed by a number of "segment_index" records (the total
number of which is the last index value in the header, starting at address
572 there). Each of the segment_index records consists of 16 bytes:

struct Segment_index
{
  unsigned char minlong[3];   /* 3-byte integer */
  unsigned char maxlong[3];   /*       "        */
  unsigned char minlat[3];    /*       "        */
  unsigned char maxlat[3];    /*       "        */
  unsigned char address[4];   /* 4-byte integer */
};

The first four 3-byte integers indicate the bounding box of the segment in
terms of longitude/latitude. The last 4-byte integer is an absolute pointer 
to the position where the segement is actually stored in the file. The
segment data themselves are stored in consecutive order after the 576-byte 
header and the list of segment_index records.

C. Each segment consists of an origin

unsigned char orgx[3],   /* 3-byte integer */
unsigned char orgy[3],   /* 3-byte integer */

where x refers to longitude and y to latitude, and a varying number N of 
strokes 

signed char dx, dy;      /* 1-byte integers */

which indicate the successive relative moves with respect to the origin
(1-byte signed integers for both dx and dy, in fact |dx|<=127 and |dy|<=127).
The total number of bytes is thus 6+2*N, and it is obtained by computing
the difference of addresses in the respective segment_index of ranks 
i and i-1 (from which N can of course be derived by subtracting 6 and 
dividing by 2...)