Basemap
Plot on map projections (with coastlines and political boundaries) using matplotlib.
Requirements
Basic requirements are the following:
- Python 2.6 (or higher)
- matplotlib
- numpy
- pyproj
- pyshp
- six
Optional requirements include:
-
OWSLib. It is needed for the
Basemap.wmsimage
function. -
Pillow. It is needed for the methods
Basemap.bluemarble
,Basemap.etopo
,Basemap.shadedrelief
andBasemap.warpimage
.
Installation
The basemap-data
and basemap-data-hires
packages are available in
PyPI and can be installed with pip
:
python -m pip install basemap-data
python -m pip install basemap-data-hires
Precompiled basemap
binary wheels for Windows and GNU/Linux are also
available in PyPI (architectures x86 and x64, Python 2.7 and 3.5+):
python -m pip install basemap
Otherwise, you will need to install basemap
from source as follows:
-
Install pre-requisite Python modules:
-
Download the
basemap
source code and move to thepackages/basemap
folder:git clone --depth 1 https://github.com/matplotlib/basemap.git cd basemap/packages/basemap
-
Build the GEOS library. You may use the helper provided in
utils
, i.e.export GEOS_DIR=<your desired location> python -c "import utils; utils.GeosLibrary('3.5.1').build(installdir='${GEOS_DIR}')"
or you can link directly to the system library if it is already installed.
GEOS_DIR
must point to the GEOS installation prefix; e.g. iflibgeos_c.so
is located in/usr/lib
andgeos_c.h
is located in/usr/include
, then you must setGEOS_DIR
to/usr
. -
Build and install the
basemap
binary wheel:python -m pip install .
On Linux, if your Python was installed through a package management system, make sure that you have the Python header
Python.h
required to build Cython extensions (e.g. on Debian-like systems, you should have the packagepython-dev
installed). -
Check that the package installed correctly by executing:
python -c "from mpl_toolkits.basemap import Basemap"
You can also test the examples available in the
examples
folder.
License
The source code and data assets are under the following licenses:
basemap
: MIT.- GEOS bundled dynamic library is under the LGPL-2.1-only license.
basemap-data
: LGPL-3.0-or-later.- The EPSG file and the JPG images are also under the MIT license.
basemap-data-hires
: LGPL-3.0-or-later.
For a full description, please visit the README
and LICENSE
files of
each package.
Documentation
See https://matplotlib.github.io/basemap/
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.
Contact
Ben Root ben.v.root@gmail.com
Víctor Molina García (@molinav)
Thanks
Special 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, Jonas Bluethgen, Chris Murphy, Pierre Gerard-Marchant, Christoph Gohlke, Eric Bruning, Stephane Raynaud, Tom Loredo, Patrick Marsh, Phil Elson, and Henry Hammond for valuable contributions.
Known bugs
The Basemap.fillcontinents
method doesn't always do the right thing.
Matplotlib always tries to fill the inside of a polygon. Under certain
situations, what is the inside of a coastline polygon can be ambiguous,
and the outside may be filled instead of the inside. A workaround is to
change the map projection region slightly or mask the land areas with
the Basemap.drawlsmask
method instead of filling the coastline
polygons (this is illustrated in the ortho_demo.py
example).