Read Me

**Descripton**

basemap - plot on map projections (with coastlines and political boundaries)
using matplotlib.

**Requirements**

python 2.4 (or higher)

matplotlib 0.98 (or higher)

numpy 1.1 (or higher)

The GEOS (Geometry Engine - Open Source) library (version 3.1.1 or higher).
Source code is included in the geos-3.2.0 directory.

PIL (http://pythonware.com/products/pil) is optional (only
needed for Basemap warpimage and bluemarble methods).

On linux, if your python was installed via a package management system, make
sure the corresponding "python-dev" package is also installed.  Otherwise, you
may not have the python header (Python.h), which is required to build python
C extensions.

**Copyright**

source code from proj.4 (http://proj.maptools.org) is included in the
'src' directory under the terms given in LICENSE_proj4.

source code for the GEOS library is
included in the 'geos-3.1.1' directory under the terms given in
LICENSE_geos.

pyshapelib by Bernhard Herzog is included in the 'pyshapelib' directory
under the terms given in LICENSE_pyshapelib.

the coastline, lake, river and political boundary data are extracted
from datasets provided with the Generic Mapping Tools
(http://gmt.soest.hawaii.edu)
and are included under the terms given in LICENSE_data.

a public domain 5-minute land/sea/lake mask dataset from
http://www.ngdc.noaa.gov/seg/cdroms/graham/graham/graham.htm
is included.

Everything else (including src/_proj.pyx, src/_geod.pyx, src/_pyproj.pxi,
src/_proj.c, src/_geod.c, src/_geos.c, and src/_geos.pyx):

copyright (c) 2007 by Jeffrey Whitaker.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notices appear in all copies and that
both the copyright notices and this permission notice appear in
supporting documentation.
THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

**Documentation** 

see http://matplotlib.sf.net/basemap/doc/html/.

see scripts in 'examples' directory for example usage.

read the FAQ and/or email the matplotlib-users mailing list if 
you have problems or questions.

**Install**

0) Install pre-requisite python modules numpy and matplotlib.

1) Then download basemap-X.Y.Z.tar.gz (approx 100 mb) from
the sourceforge download site, unpack and cd to basemap-X.Y.Z.
Note that most of that size consists of coastline data, which 
does not change with every release.  When it does change, it is
noted in the Changelog.  If you already have the latest data installed, 
you can download basemap-nodata-X.Y.Z.tar.gz instead, which is
*much* smaller.

By default the data is installed in the same directory as the toolkit. 
You may move it if you wish, and set the environment variable
BASEMAPDATA to point to the new location.

2) Install the GEOS library.  If you already have it on your
system, just set the environment variable GEOS_DIR to point to the location 
of libgeos_c and geos_c.h (if libgeos_c is in /usr/local/lib and
geos_c.h is in /usr/local/include, set GEOS_DIR to /usr/local).
Then go to step (3).  If you don't have it, you can build it from
the source code included with basemap by following these steps:

 > cd geos-3.1.1
 > export GEOS_DIR=<where you want the libs and headers to go>
   A reasonable choice on a Unix-like system is /usr/local, or
   if you don't have permission to write there, your home directory.
 > ./configure --prefix=$GEOS_DIR 
 > make; make install

3) cd back to the top level basemap directory (basemap-X.Y.Z) and
run the usual 'python setup.py install'.  Check your installation
by running "from mpl_toolkits.basemap import Basemap" at the python
prompt.

Basemap includes three auxilliary packages, pydap (http://pydap.org, just 
the client is included), httplib2 and pyshapelib.  By default, setup.py checks to 
see if these are already installed, and if so does not try to overwrite 
them. If you get import errors related to either of these two packages, 
edit setup.cfg and set pydap, httplib2 and/or pyshapelib to True to force 
installation of the included versions.

4) To test, cd to the examples directory and run 'python simpletest.py'.
To run all the examples (except those that have extra dependencies
or require an internet connection), execute 'python run_all.py'.

**Contact**

Jeff Whitaker <jeffrey.s.whitaker@noaa.gov>


**Thanks**

to

John Hunter
Andrew Straw
Eric Firing
Rob Hetland
Scott Sinclair
Ivan Lima
Erik Andersen
Michael Hearne
Jesper Larsen
Ryan May
David Huard
Mauro Cavalcanti
Chris Murphy
Pierre Gerard-Marchant
Christoph Gohlke
Eric Bruning
Stephane Raynaud

for valuable contributions.