title: World map tool

This is a simple tool for "remixing" [a public domain world map
available via Wikimedia][map] (a Robinson projection in vector graphic
format that shows all U.N. member states).  After this map was chosen
for use in a university web project, we had a need to refactor it in
various ways.  This script automates most of the operations that
we require.  It is offered
here for use by others with similar needs.

[map]: http://commons.wikimedia.org/wiki/Image:BlankMap-World6.svg

The script offers four output modes:

> Flat Map
> :    The progressive shrinkage toward the poles on the horizontal
> and vertical axes can be undone, to produce a flat map with
> parallel lines of longitude and latitude.  The flattening
> process can be reversed.
>
> Original Map
> : The original Robinson projection or a Flat Map generated by
> the script can be written out as a Robinson projection. The
> file written can be used as a drop-in replacement for the
> original Robinson projection data.
>	
> Rotated Map
> : The Robinson projection can be rotated to place an arbitrary
> line of longitude at the center.  This conversion is one-way,
> and cannot be reversed.
>
> Country Image
> : The outline of a single country can be exported using
> the -c option.  In this case, pinpoints with the "country"
> attribute set to the ID of the relevant country will be
> preserved in the output.  (The US is a bit of problem with
> this option, since the tail end of the Aleutian Islands
> wraps around to the right side of the default view.)

There are quite a few options to the script.  You can get
an overview of the possibilities by looking through The examples
directory in the distribution archive.  Some of the nice
features are:

> Pinpoint marks
> : Marks can be placed on the map at specific coordinates,
> using standard measurements of latitude and longitude.
> Pinpoint marks can be added when processing a Flat Map,
> a Rotated Map, or a Country Image.
>
> Colour and style
> : Arbitrary stylesheet code can be inserted into the file,
> for colouring and other effects.  This works with all three
> output map types and with Country Image.
>
> Clickable pages
> : The script can insert imagemaps into HTML pages for
> countries or for pinpoint marks, to support the creation
> of pages with clickable images.

The original vector graphic data is the work product of numerous
Wikipedia contributors, for whose efforts we all must be 
grateful. As it has been released to the public domain, a copy 
of the map has been incorporated into this software.

# Usage

The script itself is pretty straightfoward.  After installing the
software, open a command line terminal.  Run the command
`nugsl-worldmap` with no options to display a help screen.  Run the
script with the `-H` option to additionally display a sample entry for
the configuration files used to place pinpoint markers on the map.
Examples can be found in the `examples` directory of the
worldmap distribution archive.

The script outputs an SVG vector graphic file.  To edit the file, or
to render it into bitmap format, you will need a suitable vector
graphic editor.  [Inkscape][inkscape] is free and works quite well.  
For converting SVG files to raster images, the `rsvg` utility
available for Linux systems is a reliable performer (Inkscape
has a PNG export option, but it occasionally produces files
with glitches).

[inkscape]: http://www.inkscape.org/

Note that some recent Windows systems do not seem to be capable of
displaying SVG files locally.  This has been addressed in [security
bulletin MS07-045][bulletin] for Internet Explorer, issued by
Microsoft.  Separate [instructions][instructions] are also available.

[bulletin]: http://support.microsoft.com/kb/937143

[instructions]: http://support.microsoft.com/kb/935575


# Installation

To run the script, you will need to have the following items
installed on your system:

> [Python][python] (the script was developed using Python 2.5)

[python]: http://www.python.org/download/

> [`tagtool`][tagtool] (see below for installation instructions)

[tagtool]: http://gsl-nagoya-u.net/appendix/software/tagtool//

> [`nugsl-worldmap`][worldmap] (see below for installation instructions)

[worldmap]: http://gsl-nagoya-u.net/appendix/software/worldmap/

To install `tagtool` and `nugsl-worldmap`, expand the relevant 
`.tgz` archive in a temporary directory (**not** directly in 
Python's ``site-packages``).  Each archive contains a setup file 
`setup.py`.  OS-specific installation instructions follow.


## GNU/Linux, BSDs, Unix, Mac OS X, etc.

1. Open a shell.
2. Go to the directory created by expanding the archive::

       cd <archive_directory_path>
3. Install the package::

       python setup.py install

   If the python executable isn't on your path, you'll have to specify
   the complete path, such as /usr/local/bin/python.  You may need
   root permissions to complete this step.


## Windows

Just double-click `install.py`.  If this doesn't work, try the
following:

1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're
   calling it these days).
2. Go to the directory created by expanding the archive::

       cd <archive_directory_path>
3. Install the package::

       <path_to_python.exe>\python setup.py install